DOS 4.00 Technical Reference and Application Programming: Difference between revisions
Created page with "<PRE> DOS 4.00: TECHNICAL REFERENCE AND APPLICATION PROGRAMMING..." |
No edit summary |
||
| Line 316: | Line 316: | ||
APPENDIX D. EXPANDED MEMORY SUPPORT TRD415 3 | APPENDIX D. EXPANDED MEMORY SUPPORT TRD415 3 | ||
</PRE> | |||
==Chapter 1== | |||
</PRE> | |||
CHAPTER 1. INTRODUCTION 7 | |||
Organization of this Book 16 | |||
New DOS 4.00 Services 43 | |||
The Utilities Diskette 57 | |||
Minimum Hardware Configuration 79 | |||
CHAPTER 1. INTRODUCTION | |||
This chapter provides information about this book, including the following: | |||
Organization of the book for quick information retrieval | |||
New and enhanced DOS 4.00 services | |||
Contents of the utilities diskette | |||
Minimum hardware configuration. | |||
ORGANIZATION OF THIS BOOK | |||
This book is organized by logical application program development stages | |||
necessary to develop an application program on DOS 4.00. You must: | |||
Write the source code for the program | |||
Translate the source code to executable code | |||
Load and execute the program | |||
Debug the program | |||
Create object code libraries (optional) | |||
Convert your file formats (optional). | |||
In addition, the book tells how to make best use of the operating system by | |||
writing your own device driver or by using the system extensions. | |||
Each chapter describes a particular subject. You do not need to read the | |||
entire book to create programs or solve problems. Key topics also can be | |||
found by referring to the index and the table of contents. | |||
The appendixes contain reference information for quick retrieval. They | |||
contain the entire numerical list of DOS 4.00 services, including interrupts, | |||
function calls, and device driver services. | |||
The Technical Quick Reference contains abbreviated information about | |||
interrupts. Function calls are listed, along with input/output information | |||
and error codes. | |||
NEW DOS 4.00 SERVICES | |||
DOS 4.00 replaces IBM DOS Version 3.30 and incorporates all services | |||
previously provided by IBM DOS Version 3.30. Major new features include: | |||
Enhanced country support | |||
Double-byte character support | |||
A device driver | |||
File system support of large disk media | |||
Extended Memory Support (EMS) | |||
Performance improvements to the file system. | |||
Several function requests within interrupt 21H have been enhanced. | |||
THE UTILITIES DISKETTE | |||
A utilities diskette is included with this book. It contains a listing of | |||
the following utilities, and the description of each utility, to help | |||
programmers develop an application program: | |||
DEBUG.COM A utility to isolate and determine errors in executable | |||
programs. | |||
EXE2BIN.EXE A utility to convert executable file formats (.EXE) to | |||
.COM formats to make them more compact and, therefore, | |||
load more quickly. | |||
LIB.EXE A utility that allows the programmer to build and edit | |||
object libraries. | |||
LINK.EXE A utility to translate object code to executable code. | |||
VDISK.ASM A fully documented programming example of a device | |||
driver. However, this example does not reflect the | |||
current level of VDISK.SYS. | |||
MINIMUM HARDWARE CONFIGURATION | |||
DOS 4.00 supports the following family of IBM Personal Computers and Personal | |||
System/2 computers: | |||
The IBM Personal Computer | |||
The IBM Personal Computer XT(TM) | |||
The IBM Personal Computer XT(TM) Model 286(1) | |||
The IBM Personal Computer AT(R) (all versions)(2) | |||
The IBM PC Convertible | |||
The IBM Personal System/2(R) Model 25 (all versions) | |||
The IBM Personal System/2(R) Model 30 (all versions) | |||
The IBM Personal System/2(R) Model 50 (all versions) | |||
The IBM Personal System/2(R) Model 60 (all versions) | |||
The IBM Personal System/2(R) Model 80 (all versions). | |||
NOTE: DOS 4.00 does not support the IBM PCjr. | |||
The minimum memory requirement is 256KB. | |||
(1) Personal Computer XT is a trademark of the International Business | |||
Machines Corporation. | |||
(2) Personal Computer AT and Personal System/2 are registered trademarks of | |||
the International Business Machines Corporation. | |||
PART 1. WRITING PROGRAMS | |||
</PRE> | |||
==Chapter 10== | |||
<PRE> | |||
CHAPTER 10. DEBUGGING A PROGRAM 32 | |||
The DEBUG Utility 37 | |||
Starting the DEBUG.COM Program 46 | |||
Entering Commands at the DEBUG Prompt 67 | |||
DEBUG Command Summary 103 | |||
The DEBUG Work Space 181 | |||
A (Assemble) Command 225 | |||
C (Compare) Command 348 | |||
D (Dump) Command 400 | |||
E (Enter) Command 504 | |||
F (Fill) Command 620 | |||
G (Go) Command 669 | |||
H (Hexarithmetic) Command 771 | |||
I (Input) Command 789 | |||
L (Load) Command 811 | |||
M (Move) Command 919 | |||
N (Name) Command 973 | |||
O (Output) Command 1019 | |||
P (Proceed) Command 1040 | |||
Q (Quit) Command 1090 | |||
R (Register) Command 1113 | |||
S (Search) Command 1263 | |||
T (Trace) Command 1321 | |||
U (Unassemble) Command 1390 | |||
W (Write) Command 1513 | |||
XA (EMS Allocate) Command 1645 | |||
XD (EMS Deallocate) Command 1672 | |||
XM (EMS Map) Command 1699 | |||
XS (EMS Status) Command 1727 | |||
DEBUG Error Messages 1759 | |||
CHAPTER 10. DEBUGGING A PROGRAM | |||
This chapter describes how to use the DEBUG.COM program on the utilities | |||
diskette to identify and fix problems in your programs. | |||
THE DEBUG UTILITY | |||
DEBUG provides a controlled testing environment that enables you to monitor | |||
the execution of a program. You can make changes directly to a .COM or an | |||
.EXE file and execute the file immediately to determine whether your changes | |||
fixed a problem. You do not need to reassemble source code files first. | |||
DEBUG allows you to load, alter, or display any file and to execute object | |||
files as well. | |||
STARTING THE DEBUG.COM PROGRAM | |||
To start DEBUG, enter information in the following format: | |||
You can enter just the DEBUG command, or you can include a file | |||
specification. The parameters parm1 and parm2 represent input and output | |||
specifications of the program you are debugging. For example, suppose you | |||
wanted to monitor the execution of the DOS 4.00 DISKCOMP utility. You enter: | |||
DEBUG DISKCOMP.COM A: B: | |||
The DEBUG program loads DISKCOMP into memory and displays the DEBUG prompt: | |||
The hyphen (-) tells you DEBUG is ready to accept commands to alter, display, | |||
or execute the contents of the program in memory. | |||
If you enter just DEBUG without a file specification, you can either work | |||
with the present memory contents or you can load a required file into memory | |||
using the DEBUG NAME and LOAD commands. | |||
ENTERING COMMANDS AT THE DEBUG PROMPT | |||
A DEBUG command consists of a single letter, usually followed by one or more | |||
parameters. For example, the NAME command is entered at the DEBUG prompt as | |||
a single letter followed by a file specification: | |||
-N MYPROG | |||
A command and its parameters can be entered in uppercase, lowercase, or a | |||
combination of both. The command and its parameters can be separated by | |||
delimiters; however, delimiters are only required between two consecutive | |||
hexadecimal values. Thus, the following DUMP commands are equivalent: | |||
dcs:100 110 | |||
d cs:100 110 | |||
d,cs:100,110 | |||
A command is activated only after you press the Enter key. If you want to | |||
terminate a command and return to the DEBUG prompt, simultaneously press the | |||
Ctrl and Break keys. | |||
For commands producing a large amount of output, you can simultaneously press | |||
the Ctrl and Num Lock keys (or Pause key if available) to suspend the display | |||
and then press any key to restart the display, or you can redirect the | |||
command's output to a file. | |||
When DEBUG encounters a syntax error in a line, it displays the line with the | |||
error identified as follows: | |||
d cs:100 CS:100 | |||
&hat.error 110 | |||
In this example, the DUMP command expects the second address to contain only | |||
a hexadecimal offset value. It finds the S, which is not a hexadecimal | |||
character. | |||
DEBUG COMMAND SUMMARY | |||
The table below lists the DEBUG commands and describes the debugging | |||
operations you can perform with them. Complete format descriptions and | |||
examples for each command can be found starting on page 10-4. | |||
+---------------------------------------------------------------------------+ | |||
| COMMAND TASK DESCRIPTION | | |||
+---------------------------------------------------------------------------+ | |||
| A Assemble IBM Macro Assembler statements directly into memory. | | |||
| (Assemble) | | |||
+---------------------------------------------------------------------------+ | |||
| C Compare the contents of two blocks of memory. | | |||
| (Compare) | | |||
+---------------------------------------------------------------------------+ | |||
| D (Dump) Dump the contents of a portion of memory to the display or | | |||
| redirect it to a file. | | |||
+---------------------------------------------------------------------------+ | |||
| E (Enter) Make changes to bytes in memory. | | |||
+---------------------------------------------------------------------------+ | |||
| F (Fill) Fill a range of memory with byte values. | | |||
+---------------------------------------------------------------------------+ | |||
| G (Go) Execute the program in memory from one address to the | | |||
| breakpoint address and then display the next instruction. | | |||
+---------------------------------------------------------------------------+ | |||
| H (Hex) Add and subtract two hexadecimal values and display the | | |||
| results. | | |||
+---------------------------------------------------------------------------+ | |||
| I (Input) Display the input in the first byte next to the port. | | |||
+---------------------------------------------------------------------------+ | |||
+---------------------------------------------------------------------------+ | |||
| COMMAND TASK DESCRIPTION | | |||
+---------------------------------------------------------------------------+ | |||
| L (Load) Load the contents of absolute disk sectors or a file | | |||
| specified by the NAME command into memory. | | |||
+---------------------------------------------------------------------------+ | |||
| M (Move) Copy the contents of a block of memory to another location. | | |||
+---------------------------------------------------------------------------+ | |||
| N (Name) Set up file control blocks and file specification information | | |||
| for LOAD and WRITE commands. | | |||
+---------------------------------------------------------------------------+ | |||
| O (Output) Send a byte to an output port. | | |||
+---------------------------------------------------------------------------+ | |||
| P Execute a subroutine call, loop instruction, interrupt, or | | |||
| (Proceed) repeat string instruction and return control to DEBUG at the | | |||
| next instruction. | | |||
+---------------------------------------------------------------------------+ | |||
| Q (Quit) End the DEBUG session without saving the debugged program. | | |||
+---------------------------------------------------------------------------+ | |||
| R Display the contents of registers and the settings of flags. | | |||
| (Register) | | |||
+---------------------------------------------------------------------------+ | |||
| S (Search) Search a range of memory for characters. | | |||
+---------------------------------------------------------------------------+ | |||
| T (Trace) Execute one or more instructions in your program and display | | |||
| the contents of registers and flags after each instruction. | | |||
+---------------------------------------------------------------------------+ | |||
| U Translate the contents of memory into Assembler-like | | |||
| (Unassemble)statements, displaying their addresses and hexadecimal | | |||
| values. | | |||
+---------------------------------------------------------------------------+ | |||
| W (Write) Write the debugged program to absolute disk sectors or to the | | |||
| original file loaded with DEBUG. | | |||
+---------------------------------------------------------------------------+ | |||
| XA Allocate a specified number of expanded memory pages to an | | |||
| (Allocate) EMS handle. | | |||
+---------------------------------------------------------------------------+ | |||
| XD Deallocate an EMS handle. | | |||
| (Deallocate) | | |||
+---------------------------------------------------------------------------+ | |||
| XM (Map) Map an EMS logical page to an EMS physical page from an EMS | | |||
| handle. | | |||
+---------------------------------------------------------------------------+ | |||
| XS Display the status of expanded memory. | | |||
| (Status) | | |||
+---------------------------------------------------------------------------+ | |||
THE DEBUG WORK SPACE | |||
When the DEBUG program starts, the registers and flags are set to the | |||
following values for the program being debugged: | |||
The segment registers (CS, DS, ES, and SS) are set to the bottom of free | |||
memory; that is, the first segment after the end of the DEBUG program. | |||
The Instruction Pointer (IP) is set to hex 0100. | |||
The Stack Pointer (SP) is set to the end of the segment, or the bottom of | |||
the transient portion of the program loader, whichever is lower. The | |||
segment size at offset 6 is reduced by hex 100 to allow for a stack that | |||
size. | |||
The remaining registers (AX, BX, CX, DX, BP, SI, and DI) are set to 0. | |||
However, if you start the DEBUG program with a file specification, the CX | |||
register contains the length of the file in bytes. If the file is | |||
greater than 64KB, the length is contained in registers BX and CX (the | |||
high portion in BX). | |||
The initial state of the flags is: | |||
NV UP EI PL NZ NA PO NC | |||
The default disk transfer address is set to hex 80 in the code segment. | |||
All of available memory is allocated. At this point, the loaded program is | |||
unable to allocate memory. | |||
.EXE Files | |||
If a file loaded by DEBUG has an extension of .EXE, DEBUG does the necessary | |||
relocation and sets the segment registers, stack pointer, and instruction | |||
pointer to the values defined in the file. The DS and ES registers, however, | |||
point to the program segment prefix at the lowest available segment. The BX | |||
and CX registers contain the size of the program that is smaller than the | |||
file size. | |||
The program is loaded at the high end of memory if the appropriate parameter | |||
was specified when the linker created the file. | |||
.HEX Files | |||
If a file loaded by DEBUG has an extension of .HEX, the file is assumed to be | |||
in INTEL hex format, and is converted to executable form while being loaded. | |||
A (ASSEMBLE) COMMAND | |||
PURPOSE | |||
Assembles IBM Macro Assembler language statements directly into memory. | |||
FORMAT | |||
A[address] | |||
PARAMETERS | |||
address Use any of the following formats: | |||
A segment register plus an offset, such as CS:0100 | |||
A segment address plus an offset, such as 4BA:0100 | |||
An offset only, such as 100. In this case, the default | |||
segment is used. | |||
COMMENTS | |||
All numeric input to the Assemble command is in hexadecimal. The assembly | |||
statements you enter are assembled into memory at successive locations, | |||
starting with the address specified in address. If no address is specified, | |||
the statements are assembled into the area at CS:0100, if no previous | |||
Assemble command was used, or into the location following the last | |||
instruction assembled by a previous Assemble command. After all desired | |||
statements have been entered, press the Enter key when you are prompted for | |||
the next statement to return to the DEBUG prompt. | |||
DEBUG responds to invalid statements by displaying: | |||
&hat.error | |||
and re-displaying the current assemble address. | |||
DEBUG supports standard 8086/8088 assembly language syntax (and the 8087 | |||
instruction set), with the following rules: | |||
All numeric values entered are hexadecimal and can be entered as 1 | |||
through 4 characters. | |||
Prefix mnemonics are entered in front of the opcode to which they refer. | |||
They can also be entered on a separate line. | |||
The segment override mnemonics are CS:, DS:, ES:, and SS:. | |||
String manipulation mnemonics must specify the string size. For example, | |||
MOVSW must be used to move word strings and MOVSB must be used to move | |||
byte strings. | |||
The mnemonic for the far return is RETF. | |||
The assembler will automatically assemble short, near, or far jumps and | |||
calls depending on byte displacement to the destination address. These | |||
can be overridden with the NEAR or FAR prefix. For example: | |||
0100:0500 JMP 502 ;a 2 byte short jump | |||
0100:0502 JMP NEAR 505 ;a 3 byte near jump | |||
0100:0505 JMP FAR 50A ;a 5 byte far jump | |||
The NEAR prefix can be abbreviated to NE, but the FAR prefix cannot be | |||
abbreviated. | |||
DEBUG cannot tell whether some operands refer to a word memory location | |||
or a byte memory location. In this case, the data type must be | |||
explicitly stated with the prefix WORD PTR or BYTE PTR. DEBUG will also | |||
accept the abbreviations WO and BY. For example: | |||
NEG BYTE PTR [128] | |||
DEC WO [SI] | |||
DEBUG also cannot tell whether an operand refers to a memory location or | |||
to an immediate operand. DEBUG uses the common convention that operands | |||
enclosed in square brackets refer to memory. For example: | |||
MOV AX,21 ;Load AX with 21H | |||
MOV AX,[21] ;Load AX with the | |||
contents of memory | |||
location 21H | |||
Two popular pseudo-instructions have also been included. The DB opcode | |||
assembles byte values directly into memory. The DW opcode assembles word | |||
values directly into memory. For example: | |||
DB 1,2,3,4,'THIS IS AN EXAMPLE' | |||
DB 'THIS IS A QUOTE: '' | |||
DB 'THIS IS AN APOSTROPHE:'' | |||
DW 1000,2000,3000,'BACH:' | |||
All forms of the register indirect commands are supported. For example: | |||
ADD BX,34[BP+2][SI-1] | |||
POP [BP+DI] | |||
PUSH [SI] | |||
All opcode synonyms are supported. For example: | |||
LOOPZ 100 | |||
LOOPE 100 | |||
JA 200 | |||
JNBE 200 | |||
For numeric co-processor opcodes the WAIT or FWAIT prefix must be | |||
explicitly specified. For example: | |||
FWAIT FADD ST,ST(3) ;This line will | |||
;assemble a | |||
;FWAIT prefix | |||
FLD TBYTE PTR [BX] ;This line will | |||
;not | |||
EXAMPLE | |||
C>debug | |||
-a200 | |||
08B4:0200 xor ax,ax | |||
08B4:0202 mov [bx],ax | |||
08B4:0204 ret | |||
08B4:0205 | |||
C (COMPARE) COMMAND | |||
PURPOSE | |||
Compares the contents of two blocks of memory. | |||
FORMAT | |||
C range address | |||
PARAMETERS | |||
range Either of these two formats: | |||
An address followed by an offset, such as CS:100 110. | |||
An address followed by L value, where value is the number of | |||
hexadecimal bytes to be processed. For example, CS:100 L 10. | |||
The limit for range is hexadecimal 10000 or decimal 64KB. To | |||
specify a range of 64KB within 4 hexadecimal characters, enter | |||
0000 or 0 for value. | |||
address Any of these three formats: | |||
A segment register plus an offset, such as CS:0100. | |||
A segment address plus an offset, such as 4BA:0100. | |||
An offset only, such as 100. In this case, the default | |||
segment is used. | |||
COMMENTS | |||
The contents of the two blocks of memory are compared; the length of the | |||
comparison is determined from the range. If unequal bytes are found, their | |||
addresses and contents are displayed, in the form: | |||
addr1 byte1 byte2 addr2 | |||
where, the first half (addr1 byte1) refers to the location and contents of | |||
the mismatching locations in range, and the second half (byte2 addr2) refers | |||
to the byte found in address. | |||
If you enter only an offset for the beginning address of range, the C command | |||
assumes the segment contained in the DS register. To specify an ending | |||
address for range, enter it with only an offset value. | |||
EXAMPLE | |||
C 100 L20 200 | |||
The 32 bytes (hex 20) of memory beginning at DS:100 are compared with the 32 | |||
bytes beginning at DS:200. L20 is the range. | |||
D (DUMP) COMMAND | |||
PURPOSE | |||
Displays the contents of a portion of memory. | |||
FORMAT | |||
D [address] | |||
or | |||
D [range] | |||
PARAMETERS | |||
address Any of the following formats: | |||
A segment register plus an offset, such as CS:0100. | |||
A segment address plus an offset, such as 4BA:0100. | |||
An offset only, such as 100. In this case, the default | |||
segment is used. | |||
range Either of these two formats: | |||
An address followed by an offset, such as CS:100 110. | |||
An address followed by L value, where value is the number of | |||
hexadecimal bytes to be processed. For example, CS:100 L 10. | |||
The limit for range is hexadecimal 10000 or decimal 64K bytes. | |||
To specify a range of 64K bytes within 4 hexadecimal characters, | |||
enter 0000 or 0 for value. | |||
COMMENTS | |||
The dump is displayed in two parts: | |||
1. A hexadecimal portion. Each byte is displayed in hexadecimal. | |||
2. An ASCII portion. The bytes are displayed as ASCII characters. | |||
Unprintable characters (ASCII 0 to 31 and 127 to 255) are indicated by a | |||
period. | |||
With a 40-column system display format, each line begins on an 8-byte | |||
boundary and shows 8 bytes. | |||
With an 80-column system display format, each line begins on a 16-byte | |||
boundary and shows 16 bytes. There is a hyphen between the 8th and 9th | |||
bytes. | |||
NOTE: The first line may have fewer than 8 or 16 bytes if the starting | |||
address of the dump is not on a boundary. In this case, the second | |||
line of the dump begins on a boundary. | |||
The Dump command has two format options. | |||
OPTION 1 | |||
Use this option to display the contents of hex 40 bytes (40-column mode) or | |||
hex 80 bytes (80-column mode). For example: | |||
D address | |||
or | |||
D | |||
The contents are dumped starting with the specified address. | |||
If you do not specify an address, the D command assumes the starting address | |||
is the location following the last location displayed by a previous D | |||
command. Thus, it is possible to dump consecutive 40-byte or 80-byte areas | |||
by entering consecutive D commands without parameters. | |||
If no previous D command was entered, the location is offset hex 100 into the | |||
segment originally initialized in the segment registers by DEBUG. | |||
NOTE: If you enter only an offset for the starting address, the D command | |||
assumes the segment contained in the DS register. | |||
OPTION 2 | |||
Use this option to display the contents of the specified address range. For | |||
example: | |||
D range | |||
NOTE: If you enter only an offset for the starting address, the D command | |||
assumes the segment contained in the DS register. If you specify an | |||
ending address, enter it with only an offset value. | |||
For example: | |||
D cs:100 10C | |||
A 40-column display format might look like this: | |||
04BA:0100 42 45 52 54 41 20 54 00 | |||
BERTA T. | |||
04BA:0108 20 42 4F 52 47 | |||
BORG | |||
E (ENTER) COMMAND | |||
PURPOSE | |||
Replaces the contents of one or more bytes, starting at the specified | |||
address, with the values contained in the list (see Option 1). | |||
Displays and allows modification of bytes in a sequential manner (see | |||
Option 2). | |||
FORMAT | |||
E address [list] | |||
PARAMETERS | |||
address Any of the following formats: | |||
A segment register plus an offset, such as CS:0100. | |||
A segment address plus an offset, such as 4BA:0100. | |||
An offset only, such as 100. In this case, the default | |||
segment is used. | |||
list A string of byte values. If you include a character string, | |||
enclose the characters in single or double quotation marks. To | |||
specify a quotation mark as a character within the string when it | |||
is also used to delimit the string, type it twice. | |||
'These ''quotes'' are correct.' | |||
'This one''s okay, too.' | |||
COMMENTS | |||
If you enter only an offset for the address, the E command assumes the | |||
segment contained in the DS register. | |||
The Enter command has two format options. | |||
OPTION 1 | |||
Use this option to place the list in memory beginning at the specified | |||
address. | |||
E address list | |||
For example: | |||
E ds:100 F3 'xyz' 8D | |||
Memory locations ds:100 through ds:104 are filled with the 5 bytes specified | |||
in the list. | |||
OPTION 2 | |||
Use this option to display the address and the byte of a location, then the | |||
system waits for your input. | |||
For example: | |||
E address | |||
Enter a 1- or 2-character hexadecimal value to replace the contents of the | |||
byte; then take any one of the following actions: | |||
1. Press the space bar to advance to the next address. Its contents are | |||
displayed. If you want to change the contents take option 1, above. | |||
To advance to the next byte without changing the current byte, press the | |||
space bar again. | |||
2. Enter a hyphen to back up to the preceding address. A new line is | |||
displayed with the preceding address and its contents. If you want to | |||
change the contents, take option 1, above. | |||
To back up one more byte without changing the current byte, enter another | |||
hyphen. | |||
3. Press the Enter key to end the Enter command. | |||
NOTE: Display lines can have 4 or 8 bytes of data, depending on whether the | |||
system display format is 40- or 80-column. Spacing beyond an 8-byte | |||
boundary causes a new display line, with the beginning address, to be | |||
started. | |||
For example: | |||
E cs:100 | |||
might cause this display: | |||
04BA:0100 EB. | |||
To change the contents of 04BA:0100 from hex EB to hex 41, enter 41. | |||
04BA:0100 EB.41 | |||
To see the contents of the next three locations, press the space bar three | |||
times. The screen might look like this: | |||
04BA:0100 EB.41 10. 00. BC. | |||
To change the contents of the current location (04BA:0103) from hex BC to hex | |||
42, enter 42. | |||
04BA:0100 EB.41 10. 00. BC.42 | |||
Now, suppose you want to back up and change the hex 10 to hex 6F. This is | |||
what the screen looks like after entering two hyphens and the replacement | |||
byte: | |||
04BA:0100 EB.41 10.00. BC.42- | |||
04BA:0102 00.- | |||
04BA:0101 10.6F | |||
Press the Enter key to end the Enter command. The hyphen prompt will appear. | |||
F (FILL) COMMAND | |||
PURPOSE | |||
Fills the memory locations in the range with the values in the list. | |||
FORMAT | |||
F range list | |||
PARAMETERS | |||
range Either of these two formats: | |||
An address followed by an offset, such as CS:100 110 | |||
An address followed by L value, where value is the number of | |||
hexadecimal bytes to be processed. For example, CS:100 L 10. | |||
The limit for range is hexadecimal 10000 or decimal 64K bytes. | |||
To specify a range of 64K bytes within 4 hexadecimal characters, | |||
enter 0000 or 0 for value. | |||
list A string of byte values. If you include a character string, | |||
enclose the characters in single or double quotation marks. To | |||
specify a quotation mark as a character within the string when it | |||
is also used to delimit the string, type it twice. | |||
'These ''quotes'' are correct.' | |||
'This one''s okay, too.' | |||
COMMENTS | |||
If the list contains fewer bytes than the address range, the list is used | |||
repeatedly until all the designated memory locations are filled. | |||
If the list contains more bytes than the address range, the extra list items | |||
are ignored. | |||
NOTE: If you enter only an offset for the starting address of the range, the | |||
Fill command assumes the segment contained in the DS register. | |||
EXAMPLE | |||
F 4BA:100 L 5 F3 'XYZ' 8D | |||
Memory locations 04BA:100 through 04BA:104 are filled with the 5 bytes | |||
specified. Remember that the ASCII values of the list characters are stored. | |||
Thus, locations 100-104 will contain F3 58 59 5A 8D. | |||
G (GO) COMMAND | |||
PURPOSE | |||
Executes the program you are debugging. | |||
Stops the execution when the instruction at a specified address is reached | |||
(breakpoint), and displays the registers, flags, and the next instruction to | |||
be executed. | |||
FORMAT | |||
G [=address] [address [address...]] | |||
PARAMETERS | |||
address Any of the following formats: | |||
A segment register plus an offset, such as CS:0100. | |||
A segment address plus an offset, such as 4BA:0100. | |||
An offset only, such as 100. In this case, the default | |||
segment is used. | |||
COMMENTS | |||
Program execution begins with the current instruction, whose address is | |||
determined by the contents of the CS and IP registers, unless overridden by | |||
the =address parameter (the = must be entered). If =address is specified, | |||
program execution begins with CS:=address. | |||
The Go command has two format options. | |||
OPTION 1 | |||
Use this option to execute the program you are debugging without breakpoints. | |||
For example: | |||
G [=address] | |||
This option is useful when testing program execution with different | |||
parameters each time. (Refer to the Name command.) Be certain the CS:IP | |||
values are set properly before issuing the G command, if not using =address. | |||
OPTION 2 | |||
This option performs the same function as Option 1 but, in addition, allows | |||
breakpoints to be set at the specified addresses. For example: | |||
G [=address] address | |||
[address...] | |||
This method causes execution to stop at a specified location so the system or | |||
program environment can be examined. | |||
You can specify up to ten breakpoints in any order. You may wish to take | |||
advantage of this if your program has many paths, and you want to stop the | |||
execution no matter which path the program takes. | |||
The DEBUG program replaces the instruction codes at the breakpoint addresses | |||
with an interrupt code (hex CC). If any one breakpoint is reached during | |||
execution, the execution is stopped, the registers and flags are displayed, | |||
and all the breakpoint addresses are restored to their original instruction | |||
codes. If no breakpoint is reached, the instructions are not restored. | |||
NOTES: | |||
1. Once a program has reached completion (DEBUG has displayed the "Program | |||
terminated normally" message), you must reload the program before it can | |||
be executed again. | |||
2. Make sure that the address parameters refer to locations that contain | |||
valid 8086/8088 instruction codes. If you specify an address that does | |||
not contain valid instruction in the first byte, unpredictable results | |||
occur. | |||
3. The stack pointer must be valid and have 6 bytes available for the Go | |||
command, otherwise, unpredictable results occur. | |||
4. If only an offset is entered for a breakpoint, the G command assumes the | |||
segment contained in the CS register. | |||
5. Do not set breakpoints at instructions in read-only memory (ROM BIOS or | |||
ROM BASIC). | |||
For example: | |||
G 102 1EF 208 | |||
Be careful not to set a breakpoint between a segment override indication | |||
(such as ES; alone on a line), and the instruction that the override | |||
qualifies. | |||
Execution begins with the current instruction, whose address is the current | |||
values of CS:IP. The =address parameter was not used. | |||
Three breakpoints are specified; assume that the second is reached. | |||
Execution stops before the instruction at location CS:1EF is executed, the | |||
original instruction codes are restored, all three breakpoints are removed, | |||
the display occurs, and the Go command ends. | |||
Refer to the Register command for a description of the display. | |||
H (HEXARITHMETIC) COMMAND | |||
PURPOSE | |||
Adds the two hexadecimal values, then subtracts the second from the first. | |||
Displays the sum and difference on one line. | |||
FORMAT | |||
H value value | |||
EXAMPLE | |||
H 0F 8 | |||
0017 0007 | |||
The hexadecimal sum of 000F and 0008 is 0017, and their difference is 0007. | |||
I (INPUT) COMMAND | |||
PURPOSE | |||
Inputs and displays (in hexadecimal) 1 byte from the specified port. | |||
FORMAT | |||
I portaddress | |||
PARAMETERS | |||
portaddress A 1-4 character hexadecimal value specifying an 8- or 16-bit port | |||
address. | |||
EXAMPLE | |||
I 2F8 | |||
6B | |||
The single hexadecimal byte read from port 02F8 is displayed (6B). | |||
L (LOAD) COMMAND | |||
PURPOSE | |||
Loads a file or absolute disk sectors into memory. | |||
FORMAT | |||
L [address[drive sector sector]] | |||
PARAMETERS | |||
address Any of the following formats: | |||
A segment register plus an offset, such as CS:0100. | |||
A segment address plus an offset, such as 4BA:0100. | |||
An offset only, such as 100. In this case, the default | |||
segment is used. | |||
drive A decimal number that indicates a particular drive. For example, | |||
drive A is 0, drive B is 1, and so on. | |||
sector 1-3 character hexadecimal values that specify the starting | |||
relative sector number and the number of sectors to be loaded or | |||
written. | |||
NOTE: Relative sector numbers are obtained by counting the | |||
sectors on the disk surface. The first sector on the disk | |||
is at track 0, sector 1, head 0, and is relative sector 0. | |||
The numbering continues for each sector on that track and | |||
head, then continues with the first sector on the next | |||
head of the same track. When all sectors on all heads of | |||
the track have been counted, numbering continues with the | |||
first sector on head 0 of the next track. | |||
COMMENTS | |||
The maximum number of sectors that can be loaded with a single Load command | |||
is hex 80. A sector contains 512 bytes. | |||
NOTE: DEBUG displays a message if a disk read error occurs. You can retry | |||
the read operation by pressing the F3 key to re-display the Load | |||
command. Then press the Enter key. | |||
The Load command has two format options. | |||
OPTION 1 | |||
Use this option to load data from the disk specified by drive and place the | |||
data in memory beginning at the specified address. For example: | |||
L address drive sector sector | |||
The data is read from the specified starting relative sector (first sector) | |||
and continues until the requested number of sectors is read (second sector). | |||
NOTE: If you only enter an offset for the beginning address, the L command | |||
assumes the segment contained in the CS register. | |||
For example, to load data, you might enter: | |||
L DS:100 1 0F 6D | |||
The data is loaded from the diskette in drive B and placed in memory | |||
beginning at DS:100. Consecutive sectors of data are transferred, 6DH (109), | |||
starting with relative sector hex 0F (15) (the 16th sector on the diskette). | |||
NOTE: Option 1 cannot be used if the drive specified is a network drive. | |||
OPTION 2 | |||
When issued without parameters, or with only the address parameter, use this | |||
option to load the file whose file specification is at CS:80. For example: | |||
L | |||
or | |||
L address | |||
This condition is met by specifying the file name when starting the DEBUG | |||
program, or by using the Name command. | |||
NOTE: If DEBUG was started with a file specification and subsequent Name | |||
commands were used, you may need to enter a new Name command for the | |||
proper file specification before issuing the Load command. | |||
The file is loaded into memory beginning at CS:100 (or the location specified | |||
by address), and is read from the drive specified in the file specification, | |||
or from the default drive, if none was specified. Note that files with | |||
extensions of .COM or .EXE are always loaded at CS:100. If you specified an | |||
address, it is ignored. | |||
The BX and CX registers are set to the number of bytes read; however, if the | |||
file being loaded has an extension of .EXE, the BX and CX registers are set | |||
to the actual program size. The file may be loaded at the high end of | |||
memory. Refer to "The DEBUG Work Space" on page 10-3 for the conditions that | |||
are in effect when .EXE or .HEX files are loaded. | |||
For example: | |||
DEBUG | |||
-N myprog | |||
-L | |||
The file named MYPROG is loaded from the default directory and placed in | |||
memory beginning at location CS:0100. | |||
M (MOVE) COMMAND | |||
PURPOSE | |||
Moves the contents of the memory locations specified by range to the | |||
locations beginning at the address specified. | |||
FORMAT | |||
M range address | |||
PARAMETERS | |||
range Either of these two formats: | |||
An address followed by an offset, such as CS:100 110. | |||
An address followed by L value, where value is the number of | |||
hexadecimal bytes to be processed. For example, CS:100 L 10. | |||
The limit for range is hexadecimal 10000 or decimal 64KB. To | |||
specify a range of 64KB within 4 hexadecimal characters, enter | |||
0000 or 0 for value. | |||
address Any of the following formats: | |||
A segment register plus an offset, such as CS:0100. | |||
A segment address plus an offset, such as 4BA:0100. | |||
An offset only, such as 100. In this case, the default | |||
segment is used. | |||
COMMENTS | |||
Overlapping moves are always performed without loss of data during the | |||
transfer. (The source and destination areas share some of the same memory | |||
locations.) | |||
The data in the source area remains unchanged unless overwritten by the move. | |||
NOTES: | |||
1. If you enter only an offset for the beginning address of the range, the M | |||
command assumes the segment contained in the DS register. If you specify | |||
an ending address for the range, enter it with only an offset value. | |||
2. If you enter only an offset for the address of the destination area, the | |||
M command assumes the segment contained in the DS register. | |||
EXAMPLE | |||
M CS:100 L10 500 | |||
The 17 bytes of data from CS:100 through CS:110 are moved to the area of | |||
memory beginning at DS:500. | |||
N (NAME) COMMAND | |||
PURPOSE | |||
Formats file control blocks for the first two file specifications, at | |||
CS:5C and CS:6C. (Starting DEBUG with a file specification also formats | |||
a file control block at CS:5C.) | |||
The file control blocks are set up for the Load and Write commands and to | |||
supply required file names for the program being debugged. | |||
All file specifications and other parameters, including delimiters, are | |||
placed exactly as entered in a parameter save area at CS:81, with CS:80 | |||
containing the number of characters entered. Register AX is set to | |||
indicate the validity of the drive specifiers entered with the first two | |||
file specifications. | |||
FORMAT | |||
N [d:][path]filename[.ext] | |||
COMMENTS | |||
If you start the DEBUG program without a file specification, you must use the | |||
Name command before a file can be loaded with the L command. | |||
EXAMPLE | |||
DEBUG | |||
-N myprog | |||
-L | |||
To define file specifications or other parameters required by the program | |||
being debugged, enter: | |||
DEBUG myprog | |||
-N file1 file2 | |||
In this example, DEBUG loads the file MYPROG at CS:100, and leaves the file | |||
control block at CS:5C formatted with the same file specification. Then, the | |||
Name command formats file control blocks for file1 and file2 at CS:5C and | |||
CS:6C, respectively. The file control block for MYPROG is overwritten. The | |||
parameter area at CS:81 contains all characters entered after the N, | |||
including all delimiters, and CS:80 contains the count of those characters | |||
(hex 0C). | |||
O (OUTPUT) COMMAND | |||
PURPOSE | |||
Sends the byte to the specified output port. | |||
FORMAT | |||
O portaddress byte | |||
PARAMETERS | |||
portaddress A 1-4 character hexadecimal value specifying an 8- or 16-bit port | |||
address. | |||
EXAMPLE | |||
To send the byte value 4F to output port 2F8, enter: | |||
O 2F8 4F | |||
P (PROCEED) COMMAND | |||
PURPOSE | |||
Causes the execution of a subroutine call, a loop instruction, an interrupt, | |||
or a repeat string instruction to stop at the next instruction. | |||
FORMAT | |||
P[=address][value] | |||
PARAMETERS | |||
address Any of the following formats: | |||
A segment register plus an offset, such as CS:0100. | |||
A segment address plus an offset, such as 4BA:0100. | |||
An offset only, such as 100. In this case, the default | |||
segment is used. | |||
value A 1-4 character hexadecimal value, specifying the number of | |||
instructions to execute. | |||
COMMENTS | |||
When at a subroutine call, a loop instruction, an interrupt, or a repeat | |||
string instruction, issue the Proceed command to execute the instruction | |||
(perform the entire function), and return control at the next instruction. | |||
The Proceed command has the same syntax as the Trace command. Specifying P0 | |||
is the same as specifying T0. | |||
EXAMPLE | |||
If the following instructions are executed: | |||
0100 CALL 1000 | |||
0103 JC 2000 | |||
. | |||
. | |||
. | |||
1000 XOR AX,AX | |||
. | |||
. | |||
. | |||
1XXX RET | |||
And if CS:IP was pointing to the CALL 1000 instruction, typing P causes the | |||
execution of the subroutine and returns control to DEBUG at the JC | |||
instruction. | |||
Q (QUIT) COMMAND | |||
PURPOSE | |||
Ends the DEBUG program. | |||
FORMAT | |||
Q | |||
COMMENTS | |||
The file that you are working on in memory is not saved by the Quit command. | |||
You must use the Write command to save the file. | |||
DEBUG returns to the command processor which then issues the normal command | |||
prompt. | |||
EXAMPLE | |||
-Q | |||
A> | |||
R (REGISTER) COMMAND | |||
PURPOSE | |||
The Register command has the following three functions: | |||
Displays the hexadecimal contents of a single register with the option of | |||
changing those contents | |||
Displays the hexadecimal contents of all the registers, plus the | |||
alphabetic flag settings, and the next instruction to be executed | |||
Displays the eight 2-letter alphabetic flag settings with the option of | |||
changing any or all of them. | |||
FORMAT | |||
R [registername] | |||
PARAMETERS | |||
registername The valid names are: | |||
AX SP CS IP | |||
BX BP DS F | |||
CX SI ES | |||
DX DI SS | |||
IP refers to the instruction pointer, and F refers to the flags | |||
register. | |||
COMMENTS | |||
When the DEBUG program starts, the registers and flags are set to certain | |||
values for the program being debugged. (Refer to "The DEBUG Work Space" on | |||
page 10-3.) | |||
DISPLAY A SINGLE REGISTER | |||
To display the contents of a single register, enter the register name: | |||
R AX | |||
The system might respond with: | |||
AX F1E4 | |||
: | |||
Now you can take one of two actions: press the Enter key to leave the | |||
contents unchanged, or change the contents of the AX register by entering a | |||
1-4 character hexadecimal value, such as hex FFF. | |||
AX F1E4 | |||
:FFF | |||
Now, pressing the Enter key changes the contents of the AX register to hex | |||
0FFF. | |||
DISPLAY ALL REGISTERS AND FLAGS | |||
To display the contents of all registers and flags and the next instruction | |||
to be executed, type: | |||
R | |||
The system responds: | |||
AX=0E00 BX=00FF CX=0007 DX=01FF SP=039D BP=0000 SI=005C DI=0000 | |||
DS=3D5B ES=3D5B SS=3D5B CS=3D5B IP=011A NV UP EI PL NZ NA PO NC | |||
3D5B:011A CD21 INT 21 | |||
The first four lines display the hexadecimal contents of the registers and | |||
the eight alphabetic flag settings. The last line indicates the location of | |||
the next instruction to be executed and its hexadecimal and unassembled | |||
formats. This is the instruction pointed to by CS:IP. | |||
A system with an 80-column display shows: | |||
1st line - 8 registers | |||
2nd line - 5 registers and 8 flag settings | |||
3rd line - next instruction information | |||
A system with a 40-column display shows: | |||
1st line - 4 registers | |||
2nd line - 4 registers | |||
3rd line - 4 registers | |||
4th line - 1 register and 8 flag settings | |||
5th line - next instruction information | |||
Display All Flags | |||
There are eight flags, each with two-letter codes to indicate either a set | |||
condition or a clear condition. The flags appear in displays in the order | |||
shown in the following table: | |||
+---------------------------------------------------------------------------+ | |||
| FLAG NAME SET CLEAR | | |||
+---------------------------------------------------------------------------+ | |||
| Overflow (yes/no) OV NV | | |||
+---------------------------------------------------------------------------+ | |||
| Direction (decrease/increase) DN UP | | |||
+---------------------------------------------------------------------------+ | |||
| Interrupt (enable/disable) EI DI | | |||
+---------------------------------------------------------------------------+ | |||
| Sign (negative/positive) NG PL | | |||
+---------------------------------------------------------------------------+ | |||
| Zero (yes/no) ZR NZ | | |||
+---------------------------------------------------------------------------+ | |||
| Auxiliary carry (yes/no) AC NA | | |||
+---------------------------------------------------------------------------+ | |||
| Parity (even/odd) PE PO | | |||
+---------------------------------------------------------------------------+ | |||
| Carry (yes/no) CY NC | | |||
+---------------------------------------------------------------------------+ | |||
To display all flags, enter: | |||
R F | |||
If all the flags are in a set condition, the response is: | |||
OV DN EI NG ZR AC PE CY - | |||
Now you can either press the Enter key to leave the settings unchanged or | |||
change any or all of the settings. | |||
To change a flag, just enter its opposite code. The opposite codes can be | |||
entered in any order with or without intervening spaces. For example, to | |||
change the first, third, fifth, and seventh flags, enter: | |||
OV DN EI NG ZR AC PE CY - PONZDINV | |||
The changes in this example are entered in reverse order. | |||
Press the Enter key and the flags are modified as specified, the prompt | |||
appears, and you can enter the next command. | |||
If you want to see if the new codes are in effect, enter: | |||
R F | |||
The response is: | |||
NV DN DI NG NZ AC PO CY - | |||
The first, third, fifth, and seventh flags are changed as requested. The | |||
second, fourth, sixth, and eighth flags are unchanged. A single flag can be | |||
changed only once for each R F command. | |||
S (SEARCH) COMMAND | |||
PURPOSE | |||
Searches the range for the character(s) in the list. | |||
FORMAT | |||
S range list | |||
range Either of these two formats: | |||
An address followed by an offset, such as CS:100 110. | |||
An address followed by L value, where value is the number of | |||
hexadecimal bytes to be processed. For example, CS:100 L 10. | |||
The limit for range is hexadecimal 10000 or decimal 64KB. To | |||
specify a range of 64KB within 4 hexadecimal characters, enter | |||
0000 or 0 for value. | |||
list A string of byte values. If you include a character string, | |||
enclose the characters in single or double quotation marks. To | |||
specify a quotation mark as a character within the string when it | |||
is also used to delimit the string, type it twice. | |||
'These ''quotes'' are correct.' | |||
'This one''s okay, too.' | |||
COMMENTS | |||
All matches are indicated by displaying the addresses where matches are | |||
found. | |||
A display of the prompt without an address means that no match was found. | |||
NOTE: If you enter only an offset for the starting address of the range, the | |||
S command assumes the segment contained in the DS register. | |||
EXAMPLE | |||
If you want to search the range of addresses from CS:100 through CS:110 for | |||
hex 41, type: | |||
S CS:100 110 41 | |||
If two matches are found the response might be: | |||
04BA:0104 | |||
04BA:010D | |||
If you want to search the same range of addresses for a match with the 4-byte | |||
list (41 'AB' E), enter: | |||
S CS:100 L 11 41 'AB' E | |||
The starting addresses of all matches are listed. If no match is found, no | |||
address is displayed. | |||
T (TRACE) COMMAND | |||
PURPOSE | |||
Executes one or more instructions starting with the instruction at CS:IP, or | |||
at =address, if it is specified. The = must be entered. One instruction is | |||
assumed, but you can specify more than one with value. This command displays | |||
the contents of all registers and flags after each instruction executes. For | |||
a description of the display format, refer to the Register command. | |||
FORMAT | |||
T [=address][value] | |||
PARAMETERS | |||
address Any of the following formats: | |||
A segment register plus an offset, such as CS:0100. | |||
A segment address plus an offset, such as 4BA:0100. | |||
An offset only, such as 100. In this case, the default | |||
segment is used. | |||
value A 1-4 character hexadecimal value, specifying the number of | |||
instructions to execute. | |||
COMMENTS | |||
The display caused by the Trace command continues until value instructions | |||
are executed. Therefore, when tracing multiple instructions, remember you | |||
can suspend the scrolling at any time by pressing the Ctrl and the NumLock | |||
keys together, or the Pause key. Resume scrolling by entering any other | |||
character. | |||
NOTES: | |||
1. The Trace command disables all hardware interrupts before executing the | |||
user instruction, and then re-enables the interrupts when the trap | |||
interrupt occurs following the execution of the instruction. | |||
2. TRACE should not be used with any steps that change the contents of the | |||
8259 interrupt mask (ports 20 and 21). | |||
3. If you trace an INT3 instruction, the breakpoint is set at the INT3 | |||
location. | |||
EXAMPLE | |||
T | |||
If the IP register contains 011A, and that location contains B40E (MOV | |||
AH,0EH), this may be displayed: | |||
AX=0E00 BX=00FF CX=0007 DX=01FF SP=039D BP=0000 SI=005C DI=0000 | |||
DS=3D5B ES=3D5B SS=3D5B CS=3D5B IP=011C NV UP EI PL NZ NA PO NC | |||
3D5B:011C CD21 INT 21 | |||
This displays the results after the instruction at 011A is executed, and | |||
indicates the next instruction to be executed is the INT 21 at location | |||
04BA:011C. | |||
T 10 | |||
Sixteen instructions are executed (starting at CS:IP). The contents of all | |||
registers and flags are displayed after each instruction. The display stops | |||
after the 16th instruction has been executed. Displays may scroll off the | |||
screen unless you suspend the display by simultaneously pressing the Ctrl and | |||
NumLock keys, or the Pause key. | |||
U (UNASSEMBLE) COMMAND | |||
PURPOSE | |||
Unassembles instructions (that is, translates the contents of memory into | |||
assembler-like statements) and displays their addresses and hexadecimal | |||
values, together with assembler-like statements. For example, a display | |||
might look like this: | |||
04BA:0100 206472 AND [SI+72],AH | |||
04BA:0103 FC CLD | |||
04BA:0104 7665 JBE 016B | |||
FORMAT | |||
U [address] | |||
or | |||
U [range] | |||
PARAMETERS | |||
address Any of the following formats: | |||
A segment register plus an offset, such as CS:0100. | |||
A segment address plus an offset, such as 4BA:0100. | |||
An offset only, such as 100. In this case, the default | |||
segment is used. | |||
range Either of these two formats: | |||
An address followed by an offset, such as CS:100 110. | |||
An address followed by L value, where value is the number of | |||
hexadecimal bytes to be processed. For example, CS:100 L 10. | |||
The limit for range is hexadecimal 10000 or decimal 64KB. To | |||
specify a range of 64KB within 4 hexadecimal characters, enter | |||
0000 or 0 for value. | |||
COMMENTS | |||
The number of bytes to be unassembled depends on your system display format | |||
(40 or 80 columns), and which option you use with the Unassemble command. | |||
NOTES: | |||
1. In all cases, the number of bytes unassembled and displayed may be | |||
slightly more than either the amount requested or the default amount. | |||
This happens because the length of the instructions vary. Therefore, | |||
unassembling the last instruction may result in more bytes than expected. | |||
2. Make sure that the address parameters refer to locations containing valid | |||
8086/8088 instruction codes. If you specify an address that does not | |||
contain the first byte of a valid instruction, the display will be | |||
incorrect. | |||
3. If you enter only an offset for the starting address, the U command | |||
assumes the segment contained in the CS register. | |||
The Unassemble command has the following two format options: | |||
OPTION 1 | |||
Use this option to either unassemble instructions without specifying an | |||
address, or to unassemble instructions beginning with a specified address. | |||
For example: | |||
U | |||
or | |||
U address | |||
Sixteen bytes are unassembled with a 40-column display. Thirty-two bytes are | |||
unassembled in 80-column mode. | |||
Instructions are unassembled beginning with the specified address. | |||
If you do not specify an address, the U command assumes the starting address | |||
is the location following the last instruction unassembled by a previous U | |||
command. Thus, it is possible to unassemble consecutive locations, producing | |||
continuous unassembled displays, by entering consecutive U commands without | |||
parameters. | |||
If no previous U command is entered, the location is offset hex 0100 into the | |||
segment originally initialized in the segment registers by DEBUG. | |||
OPTION 2 | |||
Use this option to unassemble instructions in a specified address range. For | |||
example: | |||
U range | |||
All instructions in the specified address range are unassembled, regardless | |||
of the system display format. | |||
NOTE: If you specify an ending address, enter it with only an offset value. | |||
For example: | |||
U 04ba:0100 108 | |||
The display response may be: | |||
04BA:0100 206472 AND [SI+72],AH | |||
04BA:0103 FC CLD | |||
04BA:0104 7665 JBE 016B | |||
04BA:0106 207370 AND [BP+DI+70],DH | |||
The same display appears if you enter: | |||
U 04BA:100 L 7 | |||
or | |||
U 04BA:100 L 8 | |||
or | |||
U 04BA:100 L 9 | |||
W (WRITE) COMMAND | |||
PURPOSE | |||
Writes the data being debugged to disk. | |||
FORMAT | |||
W [address [drive sector sector]] | |||
PARAMETERS | |||
address Any of the following formats: | |||
A segment register plus an offset, such as CS:0100. | |||
A segment address plus an offset, such as 4BA:0100. | |||
An offset only, such as 100. In this case, the default | |||
segment is used. | |||
drive A decimal number that indicates a particular drive. For example, | |||
drive A is 0, drive B is 1, and so on. | |||
sector 1-3 character hexadecimal values that specify the starting | |||
relative sector number and the number of sectors to be loaded or | |||
written. | |||
NOTE: Relative sector numbers are obtained by counting the | |||
sectors on the disk surface. The first sector on the disk | |||
is at track 0, sector 1, head 0, and is relative sector 0. | |||
The numbering continues for each sector on that track and | |||
head, then continues with the first sector on the next | |||
head of the same track. When all sectors on all heads of | |||
the track have been counted, numbering continues with the | |||
first sector on head 0 of the next track. | |||
COMMENTS | |||
No more than hex 80 sectors can be written with a single Write command. A | |||
sector contains 512 bytes. | |||
DEBUG displays a message if a disk write error occurs. You can retry the | |||
write operation by pressing the F3 key to re-display the Write command, then | |||
press the Enter key. | |||
The Write command has two format options. | |||
OPTION 1 | |||
Use this option to write data to disk beginning at a specified address. For | |||
example: | |||
W address drive sector sector | |||
The data beginning at the specified address is written to the disk in the | |||
indicated drive. The data is written starting at the specified starting | |||
relative sector (first sector) and continues until the requested number of | |||
sectors are filled (second sector). | |||
NOTES: | |||
1. Be extremely careful when you write data to absolute sectors because an | |||
erroneous sector specification destroys whatever was on the disk at that | |||
location. | |||
2. If only an offset is entered for the beginning address, the W command | |||
assumes the segment is contained in the CS register. | |||
3. Remember, the starting sector and the sector count are both specified in | |||
hexadecimal. | |||
4. Option 1 cannot be used if the specified drive is a network drive. | |||
For example: | |||
W 1FD 1 100 A | |||
The data beginning at CS:01FD is written to the diskette in drive B, starting | |||
at relative sector hex 100 (256) and continuing for hex 0A (10) sectors. | |||
OPTION 2 | |||
This option permits you to use the WRITE command without specifying | |||
parameters or specifying only the address parameter. For example: | |||
W | |||
or | |||
W address | |||
When issued as shown above, the Write command writes the file (whose file | |||
specification is at CS:80) to disk. | |||
This condition is met by specifying the file when starting the DEBUG program, | |||
or by using the Name command. | |||
NOTE: If DEBUG was started with a file specification and subsequent Name | |||
commands were used, you may need to enter a new Name command for the | |||
proper file specification before issuing the Write command. | |||
In addition, the BX and CX registers must be set to the number of bytes to be | |||
written. They may have been set properly by the DEBUG or Load commands, but | |||
were changed by a Go or Trace command. You must be certain the BX and CX | |||
registers contain the correct values. | |||
The file beginning at CS:100, or at the location specified by address, is | |||
written to the diskette in the drive included in the file specification or | |||
the default drive if no drive was specified. | |||
The debugged file is written over the original file that was loaded into | |||
memory, or into a new file if the file name in the FCB didn't previously | |||
exist. | |||
NOTE: An error message is issued if you try to write a file with an | |||
extension of .EXE or .HEX. These files are written in a specific | |||
format that DEBUG cannot support. | |||
If you find it necessary to modify a file with an extension of .EXE or .HEX, | |||
and the exact locations to be modified are known, use the following | |||
procedure: | |||
1. RENAME the file to an extension other than .EXE or .HEX. | |||
2. Load the file into memory using the DEBUG or Load command. | |||
3. Modify the file as needed in memory, but do not try to execute it with | |||
the Go or Trace commands. Unpredictable results would occur. | |||
4. Write the file back using the Write command. | |||
5. RENAME the file to its correct name. | |||
XA (EMS ALLOCATE) COMMAND | |||
PURPOSE | |||
Allocates a specified number of expanded memory pages to a handle. | |||
FORMAT | |||
XA count | |||
COMMENTS | |||
The count indicates the number of 16K pages to allocate. If the amount of | |||
expanded memory identified by count is available, a message is displayed, | |||
indicating that a handle has been created. The XS (EMS Status) command can | |||
be used to display the number of expanded memory pages that are available. | |||
EXAMPLE | |||
To allocate two EMS pages, enter: | |||
XA 2 | |||
If two pages of memory are available, a message like this is displayed: | |||
Handle created = 000E | |||
XD (EMS DEALLOCATE) COMMAND | |||
PURPOSE | |||
Deallocates a handle. | |||
FORMAT | |||
XD handle | |||
COMMENTS | |||
The handle identifies the number of the handle to be deallocated. If the | |||
number is valid, a message is displayed, indicating the handle has been | |||
deallocated. The XS (EMS Status) command can be used to display the handles | |||
currently being used. | |||
EXAMPLE | |||
To deallocate a handle when you have only one allocated, you can enter: | |||
XD 000E | |||
If the handle deallocation is successful, you receive a message like this: | |||
Handle 000E deallocated. | |||
XM (EMS MAP) COMMAND | |||
PURPOSE | |||
Maps an EMS logical page to an EMS physical page from an EMS handle. | |||
FORMAT | |||
XM lpage ppage handle | |||
COMMENTS | |||
The lpage specifies the number of the handle's logical page that is to be | |||
mapped. The ppage is the number of the physical page to be mapped to. The | |||
handle is the EMS allocated label used to reference a group of logical pages. | |||
If syntax items are valid, a message is displayed indicating that the logical | |||
page has been mapped to the physical page. | |||
EXAMPLE | |||
To map a logical page to a physical page using handle 0001, you can enter: | |||
XM 1 0 1 | |||
If the mapping is successful, you receive this message: | |||
Logical page 01 mapped to physical page 00. | |||
XS (EMS STATUS) COMMAND | |||
PURPOSE | |||
Displays the status of expanded memory. | |||
FORMAT | |||
XS | |||
COMMENTS | |||
The following expanded memory information is displayed: | |||
Handle %1 has %2 pages allocated | |||
. | |||
. | |||
. | |||
Physical page %1 = Frame segment %2 | |||
. | |||
. | |||
. | |||
%1 of a total %2 EMS pages have been allocated | |||
%1 of a total %2 EMS handles have been allocated | |||
EXAMPLE | |||
A line is displayed for each handle allocated with its associated logical | |||
page count. | |||
DEBUG ERROR MESSAGES | |||
The following error messages are produced by the DEBUG utility: | |||
ACCESS DENIED The result of attempting to Write (W) to a | |||
read-only file. | |||
DISK ERROR READING DRIVE %1 An invalid parameter was entered on the | |||
Load (L) command or an error occurred on | |||
issuing the Load (L) command. | |||
DISK ERROR WRITING DRIVE %1 An invalid parameter was entered on the | |||
Write (W) command or an error occurred on | |||
issuing the Write (W) command. | |||
EMS HARDWARE/SOFTWARE FAILURE The result of an EMS command. Tells the | |||
user EMS is not functioning properly. | |||
EMS NOT INSTALLED The result of an EMS command. Tells user | |||
EMS is not installed. | |||
&HAT. ERROR Points to the offending operand in an error | |||
condition. | |||
ERROR IN EXE OR HEX FILE The EXE or HEX file are in error. | |||
EXE AND HEX FILES CANNOT BE WRITTEN A file in EXE or HEX format cannot be | |||
written to a disk. | |||
EXEC FAILURE The execution of the requested file failed. | |||
FILE CREATION ERROR The result of attempting to Write (W) to a | |||
system or hidden file. | |||
FILE NOT FOUND Issued from the Load (L) command when a | |||
file is not found for loading. | |||
FREE PAGES EXCEEDED The result of an EMS command. Tells the | |||
user that the request has exceeded the | |||
amount of free EMS pages available. | |||
HANDLE NOT FOUND The result of an EMS command. Tells the | |||
user an EMS handle was not found. | |||
INCORRECT DOS VERSION Incorrect version of DEBUG for the DOS | |||
version running. | |||
INSUFFICIENT MEMORY Not enough memory to Load (L) the specified | |||
file. | |||
INSUFFICIENT SPACE ON DISK Out of disk space for a Write (W) command. | |||
INVALID DRIVE SPECIFICATION The drive referenced by the Name (N) and | |||
Load (L) command is invalid; that is, it | |||
does not exist. | |||
LOGICAL PAGE OUT OF RANGE The result of an EMS command. Tells the | |||
user that the logical page requested is not | |||
in the range of possible pages. | |||
MISSING OR INVALID EMS PARAMETER The result of an EMS command. Tells the | |||
user a missing or invalid parameter was | |||
entered. | |||
NO FREE HANDLES The result of an EMS command. Tells the | |||
user that there are no more EMS handles | |||
available for allocation. | |||
PARAMETER ERROR The result of an EMS command. Tells the | |||
user that an EMS parameter is in error. | |||
PHYSICAL PAGE OUT OF RANGE The result of an EMS command. Tells the | |||
user that the physical page requested is | |||
not in the range of possible pages. | |||
PROGRAM TERMINATED NORMALLY An Interrupt 20H has been encountered, | |||
signalling program termination. | |||
TOTAL PAGES EXCEEDED The result of an EMS command. Tells the | |||
user that the total EMS pages have been | |||
exceeded. | |||
WRITE (W) ERROR, NO DESTINATION DEFINED Attempt to Write (W) to a file that | |||
has not yet been Named (N). | |||
WRITE PROTECT ERROR WRITING DRIVE %1 A Write (W) to a write-protected disk | |||
caused an error. | |||
WRITING %1 BYTES Reports the number of bytes written to a | |||
file when the Write (W) command is issued. | |||
</PRE> | |||
==Chapter 11== | |||
<PRE> | |||
CHAPTER 11. WRITING AN INSTALLABLE DEVICE DRIVER 26 | |||
Types of Device Drivers 39 | |||
Character Device Drivers 48 | |||
Block Device Drivers 55 | |||
How DOS 4.00 Installs Device Drivers 84 | |||
The Basic Parts of a Device Driver 134 | |||
The Device Driver Header 148 | |||
The Strategy Routine 274 | |||
The Interrupt Routines 283 | |||
How DOS 4.00 Passes a Request 300 | |||
Responding to Requests 392 | |||
Initialization Request 456 | |||
Media Check Request 511 | |||
Build BPB Request 630 | |||
Input and Output Requests 815 | |||
Nondestructive Input No Wait Request 879 | |||
Character Input and Output Status Requests 901 | |||
Character Input and Output Flush Requests 935 | |||
Open and Close Requests 951 | |||
Removable Media Request 983 | |||
Generic IOCTL Request 1008 | |||
Get Logical Device Request 1037 | |||
Set Logical Device Request 1055 | |||
CLOCK$ Device Driver Example 1073 | |||
CHAPTER 11. WRITING AN INSTALLABLE DEVICE DRIVER | |||
This chapter provides guide and system architecture information to support | |||
successful creation of an installable device driver. | |||
We recommend you use the information provided in this chapter in conjunction | |||
with the information provided in the VDISK.ASM file on the utilities | |||
diskette. This file contains the fully documented source code for the VDISK | |||
device driver, which emulates a fixed disk in RAM. | |||
NOTE: The example on the utilities diskette does not reflect the current | |||
level of VDISK.SYS.. | |||
TYPES OF DEVICE DRIVERS | |||
A device driver is a memory image file or an .EXE file that contains the code | |||
needed to implement a device. DOS 4.00 allows two types of device drivers to | |||
be installed: | |||
Character device drivers | |||
Block device drivers. | |||
CHARACTER DEVICE DRIVERS | |||
Character device drivers perform character I/O in a serial manner and have | |||
names such as CON, AUX, CLOCK$. You can open handles or FCBs to perform | |||
input and output to character devices. Because character device drivers have | |||
only one name, they support only one device. | |||
BLOCK DEVICE DRIVERS | |||
Block device drivers are the fixed disk or diskette drives on the system. | |||
They perform random I/O in pieces called blocks, which are usually the | |||
physical sector size of the disk. Block devices are not named as character | |||
devices are and you cannot open them. Instead they are mapped using the | |||
drive letters such as A, B, and C. | |||
A single block device driver can be responsible for one or more disk or | |||
diskette drives. For example, the first block device driver in the device | |||
chain may define four units such as A, B, C, and D. The second device driver | |||
may define three units: E, F, and G. The limit is 26 devices with the | |||
letters A through Z assigned to drives. The position of the driver in the | |||
chain determines the way in which the drive units and drive letters | |||
correspond. | |||
Support for Media Greater than 32MB | |||
A block device driver that runs in the DOS 4.00 environment can be written to | |||
process 32-bit sector numbers. This ability provides support for fixed disk | |||
media greater than 32MB. This support is described in these sections: | |||
"The Device Driver Header" on page 11-3 | |||
"Build BPB Request" on page 11-14 | |||
"Input and Output Requests" on page 11-18. | |||
DOS 4.00 also allows users to install their own device drivers that support | |||
media greater than 32MB. | |||
HOW DOS 4.00 INSTALLS DEVICE DRIVERS | |||
DOS 4.00 installs device drivers dynamically at startup time by reading and | |||
processing the DEVICE command in CONFIG.SYS. For example, if you have | |||
written a device driver called DRIVER1, include the following command in | |||
CONFIG.SYS: | |||
device=driver1 | |||
The DOS 4.00 device interface links device drivers together in a chain, | |||
permitting you to add device drivers for optional devices. | |||
Each device must be initialized. The device driver's initialization | |||
interrupt routine is called once when the device is installed. The | |||
initialization routine returns the location in memory of the ending address | |||
of the device driver. After setting the ending address field, a character | |||
device driver sets the status word and returns. | |||
DOS 4.00 processes installed character device drivers before handling default | |||
devices. To have DOS 4.00 install a new CON device (for example, in the | |||
device driver header's Name/Unit field) name the device CON and set the | |||
standard input device and standard output device bits in the attribute field. | |||
Because DOS 4.00 installs drivers anywhere in memory, care must be taken in | |||
any references to locations not in the segment. Your driver will not always | |||
be loaded at the same memory location each time. | |||
Block devices are installed in the same manner as character devices, above. | |||
Block devices return additional information such as the number of units. | |||
This number identifies the devices' logical names. For example, if the | |||
current maximum logical device letter is F at the time of the install call, | |||
and the block device driver initialization routine returns three logical | |||
units, the logical names of the devices are G, H, and I. The mapping is | |||
determined by the position of the driver in the device list and the number of | |||
units associated with the device. The number of units returned by INIT | |||
overrides the value in the name/unit field of the device header. | |||
A block device also returns a pointer to a BIOS parameter block (BPB) array. | |||
This is a pointer to an array of n word pointers, where n is the number of | |||
units defined. If all the units are the same, the array is able to point to | |||
the same BIOS parameter block, thus saving space. The array must be | |||
protected below the ending address pointer set by the return. | |||
The BPB contains information pertinent to the devices such as the sector size | |||
and the number of sectors per allocation unit. The sector size in the BPB | |||
cannot be greater than the maximum allowed size set by DOS 4.00 | |||
initialization. | |||
A block device returns the media descriptor byte passed to devices to report | |||
which parameters DOS 4.00 is using for a particular drive unit. | |||
THE BASIC PARTS OF A DEVICE DRIVER | |||
A device driver is a memory image file or an .EXE file containing the code | |||
needed to implement a device. All DOS 4.00 installable device drivers have | |||
these things in common: | |||
A device driver header, which identifies the device to DOS 4.00 and | |||
defines the strategy and interrupt entry points. Since a device driver | |||
is simply loaded and does not use a program segment prefix, the device | |||
header must be located at physical location 0 of the device driver (ORG 0 | |||
or no ORG statement). | |||
A strategy routine, which saves a pointer to the Request Header. | |||
The interrupt routines, which perform the requested operation. | |||
THE DEVICE DRIVER HEADER | |||
A device driver requires a device header containing the following: | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Pointer to next device header DWORD | | |||
+---------------------------------------------------------------------------+ | |||
| Attribute WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Pointer to device strategy routine WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Pointer to device interrupt routine WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Name/unit field 8 BYTES | | |||
+---------------------------------------------------------------------------+ | |||
Pointer to Next Device Header | |||
The device driver header is a pointer to the device header of the next device | |||
driver. It is a doubleword field set by DOS 4.00 at the time the device | |||
driver is loaded. The first word is an offset and the second word is the | |||
segment. | |||
If you are loading only one device driver, set the device header field to -1 | |||
before loading the device. If you are loading more than one device driver, | |||
set the first word of the device header field to the offset of the next | |||
device driver's header. Set the device header field of the last device | |||
driver to -1. | |||
Attribute Field | |||
The attribute field identifies the device to DOS 4.00. | |||
Bit 15 | |||
Bit 15 identifies whether the device is a block device or a character device. | |||
If bit 15 is set to 0, this indicates a block device. Setting bit 15 to 1 | |||
indicates a character device. Note how the setting of bit 15 affects the | |||
interpretation of the setting of the bits below. | |||
Bit 14 | |||
Bit 14, for both character and block devices, tells DOS 4.00 whether the | |||
device driver can handle control strings through IOCtl 44H, AL=2 through | |||
AL=5. Set bit 14 to 1 if control strings can be processed. IOCtl | |||
subfunctions permit the device driver to interpret the information passed to | |||
it, such as setting a baud rate or changing form lengths, without performing | |||
standard reads and writes. Set bit 14 to 0 if control strings cannot be | |||
processed. DOS 4.00 will return an error if an IOCtl is issued to send or | |||
receive control strings and bit 14 is set to 0. | |||
Bit 13 | |||
Bit 13 is used for both block and character devices. For block devices, set | |||
bit 13 to 0 if the media is an IBM format. Set bit 13 to 1 if the media is a | |||
non-IBM format. For character devices, set bit 13 to 0 if the driver | |||
supports output-until-busy. Set bit 13 to 1 if it does not. | |||
With the support of output-until-busy, the device driver will send characters | |||
to the device if the device is ready. If the device is not ready, the device | |||
driver will immediately return an error. | |||
Bit 12 | |||
Bit 12 is reserved. | |||
Bit 11 | |||
Set bit 11 if the device driver can handle removable media. This bit is | |||
called the open/close removable media bit. | |||
Bits 10 through 7 | |||
Bits 10 through 7 are reserved. | |||
Bit 6 | |||
Bit 6 is the generic IOCtl bit for both character and block device drivers. | |||
If this bit is set to 1, the device driver supports generic IOCtl function | |||
calls. Setting this bit to 1 also indicates support of the Get/Set Logical | |||
Drive function for a block device driver. | |||
Bits 5 and 4 | |||
Bits 5 and 4 are reserved. | |||
Bit 3 | |||
Set bit 3 to 1 if the character device is a clock device; set bit 3 to 0 if | |||
it is not. | |||
Bit 2 | |||
Set bit 2 to 1 if the character device is the NUL device; set bit 2 to 0 if | |||
it is not. Setting the bit tells DOS 4.00 whether the NUL device is being | |||
used. The NUL device cannot be reassigned. | |||
Bit 1 | |||
If bit 15 is set to 0 for a character device, set bit 1 to 1 to indicate that | |||
the character device is the current standard output device. If bit 15 is set | |||
to 1 for a block device, set bit 1 to 1 to indicate support for 32-bit sector | |||
numbers; otherwise 16-bit sector number support is assumed. | |||
Bit 0 | |||
Set bit 0 to 1 if the character device is the current standard input device; | |||
set bit 0 to 0 if it is not the current standard input device. | |||
Pointers to Strategy Routine and Interrupt Routines | |||
When DOS 4.00 passes a request to a device driver, it calls the device driver | |||
twice. These two fields point to the first and second entry points: the | |||
strategy routine and the interrupt routine. The fields are word values, so | |||
they must be in the same segment as the device header. | |||
Name/Unit Field | |||
These 8-byte fields identify a character device by name or a block device by | |||
unit. A character device name is left-justified followed by spaces, if | |||
necessary. For block devices, although DOS 4.00 automatically fills in this | |||
field with the value of number of units returned by INIT call, you may choose | |||
to place the number of units in the first place. | |||
THE STRATEGY ROUTINE | |||
DOS 4.00 calls a device driver at the strategy routine at first, passing in a | |||
request packet the information describing what DOS 4.00 wants the device | |||
driver to do. | |||
The strategy routine does not perform the request but queues the request or | |||
saves a pointer to the request packet. | |||
THE INTERRUPT ROUTINES | |||
DOS 4.00 calls the device driver's interrupt routine with no parameters | |||
immediately after the strategy routine returns. An interrupt routine's | |||
function is to perform the operation based on the queued request, process any | |||
data in the request packet, and set up information being returned to DOS | |||
4.00. | |||
It is the responsibility of the device driver to preserve the system state. | |||
For example, the device driver must save all registers on entry and restore | |||
them on exit. The stack maintained by DOS 4.00 is used to save all | |||
registers. If more stack space is needed, it is the device driver's | |||
responsibility to allocate and maintain an additional stack. | |||
All calls to device drivers are FAR calls. FAR returns should be executed to | |||
return to DOS 4.00. | |||
HOW DOS 4.00 PASSES A REQUEST | |||
DOS 4.00 passes a pointer in ES:BX to the request packet. The packet | |||
consists of a request header that contains information common to all | |||
requests, followed by data pertinent to the request being made. | |||
The structure of the request header is shown below. | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Length of the request header and subsequent data BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Unit code for block devices only BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Command code BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Status WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Reserved 8-BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Data VARIABLE | | |||
+---------------------------------------------------------------------------+ | |||
Length Field | |||
The length field identifies the length of the request header and subsequent | |||
data in bytes. | |||
Unit Code Field | |||
The unit code field identifies the requesting unit in a block device driver. | |||
If a block device driver has three units defined, for example, the possible | |||
values for the unit code field are 0, 1, or 2. | |||
Command Code Field | |||
The command code identifies the request. See "Responding to Requests" on | |||
page 11-8 for a list of command code values and request descriptions. | |||
Status Field | |||
The status word field is zero on entry and is set by the driver interrupt | |||
routine on return. | |||
Bit 15 | |||
Bit 15 is the error bit. If bit 15 is set to 1, the low order 8 bits of the | |||
status word (7-0) indicate the error code. | |||
Bits 14 - 10 | |||
Bits 14 through 10 are reserved. | |||
Bit 9 | |||
Bit 9 is the busy bit. As a response to status request call, character | |||
device drivers can set the busy bit to indicate whether or not a device is | |||
ready to perform input and output requests. Block device drivers can set the | |||
busy bit to indicate removable or nonremovable media. See "Character Input | |||
and Output Status Requests" on page 11-21 and "Removable Media Request" on | |||
page 11-23 for more information about the calls. | |||
Bit 8 | |||
Bit 8 is the done bit. If set, the operation is complete. The driver sets | |||
the done bit to 1 when it exits. | |||
Bits 7 - 0 | |||
Bits 7 through 0 are the low order 8 bits of the status word. If bit 15 is | |||
set, bits 7 through 0 contain the error codes. The error codes and errors | |||
are: | |||
CODES MEANING | |||
00 Write protect violation | |||
01 Unknown unit | |||
02 Device not ready | |||
03 Unknown command | |||
04 CRC error | |||
05 Bad drive request structure length | |||
06 Seek error | |||
07 Unknown media | |||
08 Sector not found | |||
09 Printer out of paper | |||
0A Write fault | |||
0B Read fault | |||
0C General failure | |||
0D Reserved | |||
0E Reserved | |||
0F Invalid disk change | |||
RESPONDING TO REQUESTS | |||
Each request packet that is passed to the device driver contains a command | |||
code value in the request header to tell the driver which function to | |||
perform. The table below contains the DOS 4.00 device interface command code | |||
values and the functions to be performed when these values are passed with | |||
data. Note that some of these functions are specific to either a block | |||
device or a character device. | |||
Following this table are detailed descriptions of request data structures and | |||
what the interrupt routines are expected to do. Some of these descriptions | |||
pertain to more than one command code. | |||
+---------------------------------------------------------------------------+ | |||
| COMMAND REQUEST DEVICE | | |||
| CODE DESCRIPTION TYPE | | |||
+---------------------------------------------------------------------------+ | |||
| 0 Initialization Both | | |||
+---------------------------------------------------------------------------+ | |||
| 1 Media check Block | | |||
+---------------------------------------------------------------------------+ | |||
| 2 Build BPB Block | | |||
+---------------------------------------------------------------------------+ | |||
| 3 IOCtl input (called only if bit 14 of attribute is Both | | |||
| set to 1) | | |||
+---------------------------------------------------------------------------+ | |||
| 4 Input (read) Both | | |||
+---------------------------------------------------------------------------+ | |||
| 5 Nondestructive input no wait Character | | |||
+---------------------------------------------------------------------------+ | |||
| 6 Input status Character | | |||
+---------------------------------------------------------------------------+ | |||
| 7 Input flush Character | | |||
+---------------------------------------------------------------------------+ | |||
| 8 Output (write) Both | | |||
+---------------------------------------------------------------------------+ | |||
| 9 Output (write with verify) Block | | |||
+---------------------------------------------------------------------------+ | |||
| 10 Output status Character | | |||
+---------------------------------------------------------------------------+ | |||
| 11 Output flush Character | | |||
+---------------------------------------------------------------------------+ | |||
| 12 IOCtl output (called only if bit 14 of attribute is Both | | |||
| set to 1 | | |||
+---------------------------------------------------------------------------+ | |||
| 13 Device open (called only if bit 11 of attribute is Both | | |||
| set to 1) | | |||
+---------------------------------------------------------------------------+ | |||
| 14 Device close (called only if bit 11 of attribute is Both | | |||
| set to 1) | | |||
+---------------------------------------------------------------------------+ | |||
| 15 Removable media (called only if bit 11 of attribute Block | | |||
| is set to 1) | | |||
+---------------------------------------------------------------------------+ | |||
| 19 Generic IOCtl Request (called Both | | |||
| only if bit 6 of attribute is set to 1) | | |||
+---------------------------------------------------------------------------+ | |||
| 23 Get logical device (called only if bit 6 of Block | | |||
| attribute is set to 1) | | |||
+---------------------------------------------------------------------------+ | |||
| 24 Set logical device (called only if bit 6 of Block | | |||
| attribute is set to 1) | | |||
+---------------------------------------------------------------------------+ | |||
INITIALIZATION REQUEST | |||
COMMAND CODE = 0 | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Request header 13-BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Number of units (not set by character devices) BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Ending address of resident program code DWORD | | |||
+---------------------------------------------------------------------------+ | |||
| Pointer to BPB array (not set by character devices) pointer DWORD | | |||
| to remainder of arguments | | |||
+---------------------------------------------------------------------------+ | |||
| Drive number BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| CONFIG.SYS Error Message control flag WORD | | |||
+---------------------------------------------------------------------------+ | |||
The driver must do the following: | |||
Set the number of units (block devices only). | |||
Set up the pointer to the BPB array (block devices only). | |||
Perform any initialization code (to modems, printers, and others). | |||
Set the ending address of the resident program code. | |||
Set the status word in the request header. | |||
To obtain information passed from CONFIG.SYS to a device driver at | |||
initialization time, the BPB pointer field points to a buffer containing the | |||
information passed in CONFIG.SYS following the =. This string may end with | |||
either a carriage return (0DH) or a linefeed (0AH). This information is | |||
read-only. Only system calls 01H-0CH and 30H can be issued by the | |||
initialization code of the driver. | |||
The last byte parameter contains the drive letter for the first unit of a | |||
block driver. For example, 0=A, 1=B and so forth. | |||
If an initialization routine determines that it cannot set up the device and | |||
wants to terminate without using any memory, use the following procedure: | |||
Set the number of units to 0. | |||
Set the ending address offset to 0. | |||
Set the ending address segment to the code segment (CS). | |||
If there are multiple device drivers in a single memory image file, the | |||
ending address returned by the last initialization called is the one DOS 4.00 | |||
uses. IBM recommends that all device drivers in a single memory image file | |||
return the same ending address. | |||
If initialization of your device driver fails, and you want the system to | |||
display the ERROR IN CONFIG.SYS LINE # error message, set the CONFIG.SYS | |||
error message control flag to a non-zero value. | |||
MEDIA CHECK REQUEST | |||
COMMAND CODE = 1 | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Request header 13-BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Media descriptor from DOS 4.00 BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Return BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| A pointer to the previous volume ID (if bit 11 = 1 and disk DWORD | | |||
| change is returned) | | |||
+---------------------------------------------------------------------------+ | |||
When the command code field is 1, DOS 4.00 calls Media Check for a drive unit | |||
and passes its current Media Descriptor byte. See "Media Descriptor Byte." | |||
Media Check returns one of the following: | |||
Media not changed | |||
Media changed | |||
Not sure | |||
Error code. | |||
The driver must perform the following: | |||
Set the status word in the request header. | |||
Set the return byte to: | |||
-1 for "media changed" | |||
0 for "not sure" | |||
1 for "media not changed." | |||
The driver uses the following method to determine how to set the return byte: | |||
If the media is nonremovable (a fixed disk), set the return byte to 1. | |||
If less than 2 seconds since last successful access, set the return byte | |||
to 1. | |||
If changeline not available, set the return byte to 0. | |||
If changeline is available but not active, set the return byte to 1. | |||
If the media byte in the new BPB does not match the old media byte, set | |||
the return byte to -1. | |||
If the current volume ID matches the previous volume ID, or if the serial | |||
number matches the previous serial number, set the return byte to 0. | |||
Media Descriptor Byte | |||
Currently the media descriptor byte has been defined for some media types. | |||
This byte should be identical to the media byte if the device has the non-IBM | |||
format bit off. These predefined values are: | |||
Media descriptor | |||
byte --> 1 1 1 1 1 x x x | |||
bits --> 7 6 5 4 3 2 1 0 | |||
BIT MEANING | |||
0 1=2-sided 0=not 2-sided | |||
1 1=8 sector 0=not 8 sector | |||
2 1=removable 0=not removable | |||
3-7 must be set to 1 | |||
NOTE: An exception to the above is that the media descriptor byte value of | |||
F0, which is used to indicate any media types not defined, and F9, | |||
which is used for 5.25-inch media with 2 sides and 15 sectors/tracks. | |||
Examples of current DOS 4.00 media descriptor bytes: | |||
+---------------------------------------------------------------------------+ | |||
| DISK # SECTORS/ MEDIA | | |||
| TYPE SIDES TRACK DESCRIPTOR | | |||
+---------------------------------------------------------------------------+ | |||
| Fixed disk -- -- F8H | | |||
+---------------------------------------------------------------------------+ | |||
| 5.25 inch 2 15 F9H | | |||
+---------------------------------------------------------------------------+ | |||
| 5.25 inch 1 9 FCH | | |||
+---------------------------------------------------------------------------+ | |||
| 5.25 inch 2 9 FDH | | |||
+---------------------------------------------------------------------------+ | |||
| 5.25 inch 1 8 FEH | | |||
+---------------------------------------------------------------------------+ | |||
| 5.25 inch 2 8 FFH | | |||
+---------------------------------------------------------------------------+ | |||
| 8 inch 1 26 FEH | | |||
+---------------------------------------------------------------------------+ | |||
| 8 inch 2 26 FDH | | |||
+---------------------------------------------------------------------------+ | |||
| 8 inch 2 8 FEH | | |||
+---------------------------------------------------------------------------+ | |||
| 3.5 inch 2 9 F9H | | |||
+---------------------------------------------------------------------------+ | |||
| 3.5 inch 2 18 F0H | | |||
+---------------------------------------------------------------------------+ | |||
To determine whether you are using a single-sided or a double-sided diskette, | |||
attempt to read the second side. If an error occurs, you may assume the | |||
diskette is single-sided. Media descriptor F0H may be used for those media | |||
types not described earlier. Programs should not use the media descriptor | |||
values to distinguish media. DOS 4.00 internal routines use information in | |||
the BIOS parameter block (BPB) to determine the media type of IBM-formatted | |||
diskettes. These media descriptor bytes do not necessarily indicate a unique | |||
media type. | |||
For 8-inch diskettes: | |||
FEH (IBM 3740 Format) -- Single-sided, single-density, 128 bytes per | |||
sector, soft-sectored, 4 sectors per allocation unit, 1 reserved sector, | |||
2 FATs, 68 directory entries, 77*26 sectors. | |||
FDH (IBM 3740 Format) -- Double-sided, single-density, 128 bytes per | |||
sector, soft-sectored, 4 sectors per allocation unit, 4 reserved sectors, | |||
2 FATs, 68 directory entries, 77*26*2 sectors. | |||
FEH -- Double-sided, double-density, 1024 bytes per sector, soft | |||
sectored, 1 sector per allocation unit, 1 reserved sector, 2 FATs, 192 | |||
directory entries, 77*8*2 sectors. | |||
BUILD BPB REQUEST | |||
COMMAND CODE = 2 | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Request header 13-BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Media descriptor from DOS 4.00 BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Transfer address (buffer address) DWORD | | |||
+---------------------------------------------------------------------------+ | |||
| Pointer to BPB table DWORD | | |||
+---------------------------------------------------------------------------+ | |||
DOS 4.00 calls Build BPB (BIOS Parameter Block) under the following two | |||
conditions: | |||
If "Media Changed" is returned | |||
If "Not Sure" is returned, there are no used buffers. Used buffers are | |||
buffers with changed data not yet written to the disk. | |||
The driver must do the following: | |||
Set the pointer to the BPB | |||
Set the status word in the request header. | |||
The device driver must determine the media type that is in the unit to return | |||
the pointer to the BPB table. In previous versions of IBMBIO, the FAT ID | |||
byte determined the structure and layout of the media. The FAT ID byte has | |||
only eight possible values (F8 through FF), so, as new media types are | |||
invented, the available values will soon be exhausted. With the varying | |||
media layouts, DOS 4.00 needs to be aware of the location of the FATs and | |||
directories before it asks to read them. | |||
The following paragraphs explain the method DOS 4.00 uses to determine the | |||
media type. | |||
The information relating to the BPB for a particular media is kept in the | |||
boot sector for the media. The format of the boot sector is as follows: | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| A 2-byte short JMP instruction (EBH), followed by a NOP WORD | | |||
| instruction (90H). | | |||
+---------------------------------------------------------------------------+ | |||
| Product name and version 8 BYTES | | |||
+---------------------------------------------------------------------------+ | |||
| Bytes per sector; must be power of 2 WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Sectors per allocation unit; must be power of 2 BYTE | | |||
+---------------------------------------------------------------------------+ | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Reserved sectors starting at logical sector 0 WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Number of FATs BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Maximum number of root directory entries WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Total number of sectors in media including the boot sector, WORD | | |||
| FAT areas, and directories | | |||
+---------------------------------------------------------------------------+ | |||
| Media descriptor BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Number of sectors occupied by a FAT WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Sectors per track WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Number of heads WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Number of hidden sectors WORD | | |||
+---------------------------------------------------------------------------+ | |||
The BPB information contained in the boot sector starts with the Bytes per | |||
Sector entry. The last three words are intended to help the device driver | |||
identify the media. The number of heads is useful for supporting different | |||
multihead drives with the same storage capacity but a different number of | |||
surfaces. The number of hidden sectors is useful for supporting drive | |||
partitioning schemes. | |||
For drivers that support volume identification and disk change, this call | |||
causes a new volume identification to be read from the disk. This call | |||
indicates that the disk has changed in a permissible manner. | |||
To handle the partition that is bigger than 32MB, or one that starts beyond | |||
or crosses the 32MB boundary, DOS 4.00 defines an extended BPB structure. | |||
Depending on the size of the media, you can use either the existing BPB or | |||
the extended one, which contains an additional DWORD field to indicate the | |||
size of the partition in sectors. | |||
Bit 1 of the attribute field in the block device driver header indicates | |||
whether the device can process 32-bit sector numbers. Set bit 1 to indicate | |||
32-bit support. | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Bytes per sector WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Sectors per allocation unit BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Reserved sectors starting at logical sector 0 WORD | | |||
+---------------------------------------------------------------------------+ | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Number of FATs -- 0 if not a FAT system BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Maximum number of root directory entries WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Total number of sectors in the media. This field is used to WORD | | |||
| define a partition that is less than 32MB. Setting this | | |||
| field to 0 indicates to use the total (32-bit) number of | | |||
| sectors in the media below. | | |||
+---------------------------------------------------------------------------+ | |||
| Media descriptor BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Number of sectors occupied by a FAT WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Sectors per track WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Number of heads WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Number of hidden sectors DWORD | | |||
+---------------------------------------------------------------------------+ | |||
| Total (32-bit) number of sectors in the media. This field is DWORD | | |||
| used to define a partition that is greater than 32MB, or one | | |||
| that crosses the 32MB boundary. | | |||
+---------------------------------------------------------------------------+ | |||
The extended BPB is a superset of the traditional BPB structure. To achieve | |||
the maximum compatibility between this structure and that of the traditional | |||
BPB, DOS 4.00 uses the following rule: | |||
If (the number of hidden sectors plus the total number of sectors in the | |||
media) is greater than 64KB, use the 32-bit total number of sectors in | |||
the media entry (DWORD). | |||
Otherwise, use the TOTAL NUMBER OF SECTORS IN THE MEDIA entry (WORD). | |||
A boot record exists at the beginning of each disk partition and each | |||
extended DOS 4.00 partition volume. DOS 4.00 automatically creates the | |||
extended boot record. The format of the extended boot record is: | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| A 2-byte short JMP instruction (EBH) followed by a NOP WORD | | |||
| instruction (90H). | | |||
+---------------------------------------------------------------------------+ | |||
| Product name and version 8 BYTES | | |||
+---------------------------------------------------------------------------+ | |||
| Extended BPB 25 BYTES | | |||
+---------------------------------------------------------------------------+ | |||
| Physical drive number BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Reserved BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Extended boot record signature BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Volume serial number DWORD | | |||
+---------------------------------------------------------------------------+ | |||
| Volume label 11 BYTES | | |||
+---------------------------------------------------------------------------+ | |||
| Reserved 8 BYTES | | |||
+---------------------------------------------------------------------------+ | |||
NOTE: The value of Extended boot record signature is 29H. The value of the | |||
physical drive number is always 0H or 80H. | |||
On all requests to extended drivers with a sector number in their request | |||
headers, the sector number is a DWORD. The standard DOS 4.00 block device | |||
drivers set the attribute bit 1 for 32-bit support. | |||
For each call to a device driver, DOS 4.00 checks to see if the starting | |||
sector number passed in the request can be supported by the device driver. | |||
If this value is greater than 64K for an old-style device driver, DOS 4.00 | |||
returns an UNKNOWN MEDIA (07H) device driver error. | |||
INPUT AND OUTPUT REQUESTS | |||
COMMAND CODES = 3, 4, 8, 9, 12 | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Request header 13-BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Media descriptor byte BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Transfer address (buffer address) DWORD | | |||
+---------------------------------------------------------------------------+ | |||
| Byte/sector count WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Starting sector number (If -1, use DWORD starting sector WORD | | |||
| number. This entry has no meaning for a character device.) | | |||
+---------------------------------------------------------------------------+ | |||
| For DOS 3.0 to DOS 4.00, pointer to the volume identification DWORD | | |||
| if error code 0FH is returned | | |||
+---------------------------------------------------------------------------+ | |||
| Starting 32-bit sector number. (Use this entry to the block DWORD | | |||
| device driver with the attribute bit 1 set.) | | |||
+---------------------------------------------------------------------------+ | |||
The DOS 4.00 INPUT/OUTPUT request structure can process 32-bit sector | |||
numbers, providing support for media of more than 4 billion sectors. | |||
The driver must do the following: | |||
Set the status word in the request header | |||
Perform the requested function | |||
Set the actual number of sectors or bytes transferred. | |||
No error checking is performed on an IOCtl call. However, the driver must | |||
set the return sector or byte count to the actual number of bytes | |||
transferred. | |||
Under certain circumstances the block device driver may be asked to do a | |||
WRITE operation of 64KB that seems to be a wraparound of the transfer address | |||
in the device driver request packet. This occurs because an optimization is | |||
added to the WRITE code in DOS 4.00. It will only happen on WRITEs that are | |||
within a sector size of 64KB on files that are being extended past the | |||
current end of file. The block device driver is allowed to ignore the | |||
balance of the WRITE that wraps around. For example, a WRITE of 10000H bytes | |||
of sectors with a transfer address of XXXX:1 ignores the last two bytes. | |||
Remember that a program using DOS 4.00 function calls cannot request an input | |||
or output operation of more than FFFFH bytes because a wrap around in the | |||
transfer buffer segment must occur. You can ignore bytes that would have | |||
wrapped around in the transfer segment. | |||
If the driver returns an error code of 0FH (Invalid Disk Change), it must | |||
provide a DWORD pointer to an ASCIIZ string identifying the correct volume ID | |||
and the system prompts the user to reinsert the disk. | |||
The reference count of open files on the disk maintained by OPEN and CLOSE | |||
calls allows the driver to determine when to return error 0FH. If there are | |||
no open files (reference count=0) and the disk has been changed, the I/O is | |||
valid, and error 0FH is not returned. If there are open files (reference | |||
count > 0) and the disk has been changed, an error 0FH situation may exist. | |||
DOS 4.00 IBMDOS.COM will request an OPEN or CLOSE function only if SHARE is | |||
loaded. | |||
NONDESTRUCTIVE INPUT NO WAIT REQUEST | |||
COMMAND CODE = 5 | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Request header 13-BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Byte read from device BYTE | | |||
+---------------------------------------------------------------------------+ | |||
The driver must do the following: | |||
Return a byte from the device. | |||
Set the status word in the request header. | |||
If the character device returns busy bit = 0, meaning there are characters in | |||
buffer, the next character that would be read is returned. This character is | |||
not removed from the input buffer, (that is, nondestructive input). This | |||
call allows DOS 4.00 to look ahead one input character. | |||
CHARACTER INPUT AND OUTPUT STATUS REQUESTS | |||
COMMAND CODES = 6, 10 | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Request header 13-BYTE | | |||
+---------------------------------------------------------------------------+ | |||
The driver must do the following: | |||
Perform the requested function. | |||
Set the busy bit. | |||
Set the status word in the request header. | |||
The busy bit is set differently for output and input. | |||
Output on Character Devices | |||
If the busy bit is 1 on return, a write request would wait for completion of | |||
a current request. If the busy bit is 0, no request is waiting or running. | |||
Therefore, a write request would start immediately. | |||
Input on Character Devices with a Buffer | |||
If the busy bit is 1 on return, a read request goes to the physical device. | |||
If the busy bit is 0, characters are in the device buffer and a read returns | |||
quickly. This also indicates that the user has typed something. DOS 4.00 | |||
assumes that all character devices have a type-ahead input buffer. Devices | |||
that do not have this buffer should always return busy = 0 so that DOS 4.00 | |||
does not loop endlessly, waiting for information to be put in a buffer that | |||
does not exist. | |||
CHARACTER INPUT AND OUTPUT FLUSH REQUESTS | |||
COMMAND CODES = 7, 11 | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Request header 13-BYTE | | |||
+---------------------------------------------------------------------------+ | |||
This call tells the driver to flush (terminate) all pending requests of which | |||
it has knowledge. Its primary use is to flush the input queue on character | |||
devices. | |||
The driver must set the status word in the Request Header upon return. | |||
OPEN AND CLOSE REQUESTS | |||
COMMAND CODES = 13, 14 | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Request header 13-BYTE | | |||
+---------------------------------------------------------------------------+ | |||
These calls are designed to give the device information about current file | |||
activity on the device if bit 11 of the attribute word is set. | |||
On block devices, these calls can be used to manage local buffering. The | |||
device can keep a reference count. Every OPEN increases the reference count. | |||
Every CLOSE decreases the device reference count. When the reference count | |||
is 0, there are no open files on the device. Therefore, the device should | |||
flush buffers inside the device to which it has written because the user can | |||
change the media on a removable media drive. If the media has been changed, | |||
reset the reference count to 0 without flushing the buffers. | |||
These calls are more useful on character devices. The OPEN call can send a | |||
device an initialization string. On a printer, the call can send a string to | |||
set the font or the page size so the printer is always in a known state at | |||
the start of an I/O stream. | |||
Similarly, the CLOSE call can send a post string, such as a form feed, at the | |||
end of an I/O stream. | |||
Using IOCtl to set the preliminary and ending strings provides a flexible | |||
mechanism for serial I/O device stream control. | |||
REMOVABLE MEDIA REQUEST | |||
COMMAND CODE = 15 | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Request header 13-BYTE | | |||
+---------------------------------------------------------------------------+ | |||
To use this call, set bit 11 of the attribute field to 1. Block devices can | |||
use this call only by way of a subfunction of the IOCtl function call (44H). | |||
This call is useful because it notifies a utility if it is dealing with a | |||
removable or nonremovable media drive. For example, the FORMAT utility needs | |||
to know whether a drive is removable or nonremovable because it displays | |||
different versions of some prompts. | |||
The information is returned in the busy bit of the status word. If the busy | |||
bit is 1, the media is nonremovable. If the busy bit is 0, the media is | |||
removable. | |||
No error bit checking is performed. It is assumed that this call always | |||
succeeds. | |||
GENERIC IOCTL REQUEST | |||
COMMAND CODE = 19 | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Request header 13-BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Major function BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Minor function BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Contents of SI WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Contents of DI WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Pointer to Generic IOCTL request packet DWORD | | |||
+---------------------------------------------------------------------------+ | |||
The driver must: | |||
Support the functions described under Generic IOCtl request | |||
Maintain its own track table (TrackLayout). | |||
See Appendix C, "I/O Control for Devices (IOCtl)" on page C-1 for a | |||
description of the functions provided by generic IOCtl requests. | |||
GET LOGICAL DEVICE REQUEST | |||
COMMAND CODE = 23 | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Request header 13-BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Input (unit code) BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Command code BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Status WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Reserved DWORD | | |||
+---------------------------------------------------------------------------+ | |||
SET LOGICAL DEVICE REQUEST | |||
COMMAND CODE = 24 | |||
+---------------------------------------------------------------------------+ | |||
| FIELD LENGTH | | |||
+---------------------------------------------------------------------------+ | |||
| Request header 13-BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Input (unit code) BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Command code BYTE | | |||
+---------------------------------------------------------------------------+ | |||
| Status WORD | | |||
+---------------------------------------------------------------------------+ | |||
| Reserved DWORD | | |||
+---------------------------------------------------------------------------+ | |||
CLOCK$ DEVICE DRIVER EXAMPLE | |||
This feature is a "Real-Time Clock" Board. To allow this board to be | |||
integrated into the system for TIME and DATE, a special device driver is | |||
specified by an attribute word, the CLOCK$ device. This device driver | |||
defines and performs functions like any other character device driver. Most | |||
functions will be set done bit, reset error bit, return. When a read or | |||
write to this device occurs, 6 bytes are transferred. The first 2 bytes are | |||
a word, which is the count of days since 1-1-80. The third byte is minutes; | |||
the fourth is hours; the fifth is hundredths of seconds; and the sixth is | |||
seconds. Reading the CLOCK$ device gets the date and time; writing to it | |||
sets the date and time. | |||
PART 3. APPENDIXES | |||
</PRE> | |||
==Appendix A== | |||
</PRE> | |||
APPENDIX A. DOS 4.00 INTERRUPTS 13 | |||
20H Program Terminate 21 | |||
21H Function Request 41 | |||
22H Terminate Address 46 | |||
23H Ctrl-Break Exit Address 53 | |||
24H Critical Error Handler Vector 83 | |||
25H/26H Absolute Disk Read/Write 287 | |||
27H Terminate but Stay Resident 353 | |||
28H-2EH Reserved for DOS 4.00 392 | |||
2FH Multiplex Interrupt 396 | |||
30H-3FH Reserved for DOS 4.00 695 | |||
APPENDIX A. DOS 4.00 INTERRUPTS | |||
This chapter contains information to support use of the DOS 4.00 interrupts. | |||
DOS 4.00 reserves interrupt types 20H to 3FH for its use. Absolute memory | |||
locations 80H to FFH are reserved by DOS 4.00. All interrupt values are in | |||
hexadecimal. | |||
20H PROGRAM TERMINATE | |||
Issue interrupt 20H to exit from a program. This vector transfers to the | |||
logic in DOS 4.00 to restore the terminate address, the Ctrl-Break address, | |||
and the critical error exit address to the values they had on entry to the | |||
program. All file buffers are flushed and all handles are closed. You | |||
should close all files changed in length (see function call 10H and 3EH) | |||
before issuing this interrupt. If the changed file is not closed, its | |||
length, date, and time are not recorded correctly in the directory. | |||
For a program to pass a completion code or an error code when terminating, it | |||
must use either function call 4CH (Terminate a Process) or 31H (Terminate | |||
Process and Stay Resident). These two methods are preferred over using | |||
interrupt 20H, and the codes returned by them can be interrogated in batch | |||
processing. See function call 4CH for information on the ERRORLEVEL | |||
subcommand of batch processing. | |||
IMPORTANT: Before you issue interrupt 20H, your program must ensure that the | |||
CS register contains the segment address of its program segment prefix. | |||
21H FUNCTION REQUEST | |||
Refer to each function call issued within 21H in Appendix B, "DOS 4.00 | |||
Function Calls" on page B-1. | |||
22H TERMINATE ADDRESS | |||
Control transfers to the address at this interrupt location when the program | |||
terminates. This address is copied into the program's Program Segment Prefix | |||
at the time the segment is created. You should not issue this interrupt; the | |||
EXEC function call does this for you. | |||
23H CTRL-BREAK EXIT ADDRESS | |||
If the user presses the Ctrl and Break keys during standard input, standard | |||
output, standard printer, or asynchronous communications adapter operations, | |||
an interrupt 23H is executed. If BREAK is on, the interrupt 23H is checked | |||
on most function calls (except calls 06H and 07H). If the user-written | |||
Ctrl-Break routine saves all registers, it may end with a | |||
return-from-interrupt instruction (IRET) to continue program execution. | |||
If the user-written interrupt program returns with a long return, the carry | |||
flag is used to determine whether the program will be ended. If the carry | |||
flag is set, the program is ended, otherwise execution continues (as with a | |||
return by IRET). | |||
If the user-written Ctrl-Break interrupt uses function calls 09H or 0AH, then | |||
&hat.C, carriage-return and linefeed are output. If execution is continued | |||
with an IRET, I/O continues from the start of the line. | |||
When the interrupt occurs, all registers are set to the value they had when | |||
the original function call to DOS 4.00 was made. There are no restrictions | |||
on what the Ctrl-Break handler is allowed to do, including DOS 4.00 function | |||
calls, as long as the registers are unchanged if IRET is used. | |||
When the program creates a new segment and loads in a second program it | |||
changes the Ctrl-Break address. The termination of the second program and | |||
return to the first causes the Ctrl-Break address to be restored to the value | |||
it had before execution of the second program. It is restored from the | |||
second program's Program Segment Prefix. You should not issue this | |||
interrupt. | |||
24H CRITICAL ERROR HANDLER VECTOR | |||
A critical error is returned when a DOS function cannot be performed. This | |||
error is frequently caused by a hardware condition, such as the printer being | |||
out of paper, a diskette drive door open, or a diskette out of space. When a | |||
critical error occurs within DOS 4.00, control is transferred with an | |||
interrupt 24H. On entry to the error handler, AH will have its bit 7=0 | |||
(high-order bit) if the error was a disk error (the most common occurrence), | |||
bit 7=1 if it was not. | |||
BP:SI contains the address of a Device Header Control Block from which | |||
additional information can be retrieved. See page A-5. | |||
The registers are set up for a retry operation, and an error code is in the | |||
lower half of the DI register with the upper half undefined. The error codes | |||
follow: | |||
ERROR CODE MEANING | |||
0 Attempt to write on write-protected diskette | |||
1 Unknown unit | |||
2 Drive not ready | |||
3 Unknown command | |||
4 Data error (CRC) | |||
5 Bad request structure length | |||
6 Seek error | |||
7 Unknown media type | |||
8 Sector not found | |||
9 Printer out of paper | |||
A Write fault | |||
B Read fault | |||
C General failure | |||
The user stack is in effect and contains the following from top to bottom: | |||
IP DOS 4.00 registers from issuing INT 24H | |||
CS | |||
FLAGS | |||
AX User registers at time of original | |||
BX INT 21H request | |||
CX | |||
DX | |||
SI | |||
DI | |||
BP | |||
DS | |||
ES | |||
IP From the original interrupt 21H | |||
CS from the user to DOS 4.00 | |||
FLAGS | |||
The registers are set such that if an IRET is executed, DOS 4.00 responds | |||
according to (AL) as follows: | |||
(AL) =0 ignore the error. | |||
=1 retry the operation. | |||
=2 terminate the program | |||
through interrupt 22H. | |||
=3 fail the system call | |||
in progress. | |||
NOTE: Be careful when choosing ignore as a response because this causes DOS | |||
4.00 to believe that an operation has completed successfully when it | |||
may not have. | |||
To return control from the critical error handler to a user error routine, | |||
the following should occur: | |||
Before an INT 24H occurs: | |||
1. The user application initialization code should save the INT 24H vector | |||
and replace the vector with one pointing to the user error routine. | |||
When the INT 24H occurs: | |||
2. When the user error routine receives control, it should push the flag | |||
register onto the stack, and then execute a CALL FAR to the original INT | |||
24H vector saved in step 1. | |||
3. DOS 4.00 gives the appropriate prompt, and waits for the user input | |||
(Abort, Retry, Fail or Ignore). After the user input, DOS 4.00 returns | |||
control to the user error routine at the instruction following the CALL | |||
FAR. | |||
4. The user error routine can now do any tasks necessary. To return to the | |||
original application at the point the error occurred, the error routine | |||
needs to execute an IRET instruction. Otherwise, the user error routine | |||
should remove the IP, CS, and Flag registers from the stack. Control can | |||
then be passed to the desired point. | |||
Disk Errors | |||
If it is a hard error on disk (AH bit 7=0), register AL contains the failing | |||
drive number (0 = drive A, and so on). AH bits 0-2 indicate the affected | |||
disk area and whether it was a read or write operation, as follows: | |||
Bit 0=0 if read operation, | |||
1 if write operation | |||
Bits 2-1 (affected disk area) | |||
0 0 DOS 4.00 area | |||
0 1 file allocation table | |||
1 0 directory | |||
1 1 data area | |||
AH bits 3-5 indicate which responses are valid. They are: | |||
Bit 3=0 if FAIL is not allowed | |||
=1 if FAIL is allowed | |||
Bit 4=0 if RETRY is not allowed | |||
=1 if RETRY is allowed | |||
Bit 5=0 if IGNORE is not allowed | |||
=1 if IGNORE is allowed | |||
Handling of Invalid Responses | |||
If IGNORE is specified (AL=0) and IGNORE is not allowed (bit 5=0), make the | |||
response FAIL (AL=3). | |||
If RETRY is specified (AL=1) and RETRY is not allowed (bit 4=0), make the | |||
response FAIL (AL=3). | |||
If FAIL is specified (AL=3) and FAIL is not allowed (bit 3=0), make the | |||
response END (AL=2). | |||
Other Errors | |||
If AH bit 7=1, the error occurred on a character device, or was the result of | |||
a bad memory image of the FAT. The device header passed in BP:SI can be | |||
examined to determine which case exists. If the attribute byte high-order | |||
bit indicates a block device, then the error was a bad FAT. Otherwise, the | |||
error is on a character device. | |||
If a character device is involved, the contents of AL are unpredictable and | |||
the error code is in DI as above. | |||
NOTES: | |||
1. Retry five times before giving this routine control for disk errors. | |||
When the errors are in the FAT or a directory, retry three times. | |||
2. For disk errors, this exit is taken only for errors occurring during an | |||
interrupt 21H function call. It is not used for errors during an | |||
interrupt 25H or 26H. | |||
3. This routine is entered in a disabled state. | |||
4. All registers must be preserved. | |||
5. This interrupt handler should refrain from using DOS 4.00 function calls. | |||
If necessary, it may use calls 01H through 0CH, 30H, and 59H. Use of any | |||
other call destroys the DOS 4.00 stack and leaves DOS 4.00 in an | |||
unpredictable state. | |||
6. The interrupt handler must not change the contents of the device header. | |||
7. If the interrupt handler handles errors itself rather than returning to | |||
DOS 4.00, it should restore the application program's registers from the | |||
stack, remove all but the last three words on the stack, then issue an | |||
IRET. This will return to the program immediately after the INT 21H that | |||
experienced the error. Note that if this is done, DOS 4.00 will be in an | |||
unstable state until a function call higher than 0CH is issued; | |||
therefore, it is not recommended. | |||
The recommended way to end a critical error is to use FAIL and then test | |||
the extended error code of the INT 21H. | |||
8. IGNORE requests (AL=0) are converted to FAIL for critical errors that | |||
occur on FAT or DIR sectors. | |||
9. Refer to "Responding to Errors" on page B-5 and "Extended Error Codes" on | |||
page B-5 for information on how to obtain additional error information. | |||
10. For DOS 4.00, IGNORE requests (AL=0) are converted to FAIL requests for | |||
certain critical errors (50-79). | |||
The device header pointed to by BP:SI is formatted as follows: | |||
+---------------------------------------------------------------------------+ | |||
| DWORD Pointer to next device (FFFFH if last device) | | |||
+---------------------------------------------------------------------------+ | |||
| WORD Attributes: | | |||
| Bit 15 = 1 if character device | | |||
| = 0 if block device | | |||
| If bit 15 is 1: | | |||
| Bit 0 = 1 if current standard input | | |||
| Bit 1 = 1 if current standard output | | |||
| Bit 2 = 1 if current NULL device | | |||
| Bit 3 = 1 if current CLOCK device | | |||
| Bit 14 is the IOCtl bit | | |||
+---------------------------------------------------------------------------+ | |||
| WORD pointer to device driver strategy entry point. | | |||
+---------------------------------------------------------------------------+ | |||
| WORD pointer to device driver interrupt entry point. | | |||
+---------------------------------------------------------------------------+ | |||
| 8-BYTE character device named field for block devices. The first byte is | | |||
| the number of units. | | |||
+---------------------------------------------------------------------------+ | |||
To tell if the error occurred on a block or character device, look at bit 15 | |||
in the attribute field (WORD at BP:SI+4). | |||
If the name of the character device is desired, look at the eight bytes | |||
starting at BP:SI+10. | |||
25H/26H ABSOLUTE DISK READ/WRITE | |||
Interrupt vectors 25H and 26H transfer control to the device driver. They | |||
have been extended to allow direct access to media greater than 32MB in size. | |||
Their use of the CX register is what distinguishes them from the conventional | |||
25H and 26H interrupts. Note that if the conventional format parameters are | |||
used in an attempt to access media greater than 32MB, an error code of 0207H | |||
is returned in AX. | |||
The request for extended 25H or 26H is: | |||
MOV AL,DRIVE ; Drive number to process | |||
; 0 = A | |||
; 1 = B | |||
; 2 = C . . . | |||
LDS BX,PACKET ; Parameter list | |||
MOV CX,-1 ; Indicates extended format | |||
INT 25H or 26H ; Issue request to DOS 4.00 | |||
POP AX ; Discard stack word | |||
JC ERROR ; Error code returned in AX | |||
PACKET LABEL BYTE ; Control packet | |||
DD RBA ; RBA of first sector | |||
; (0 origin) | |||
DW COUNT ; Number of sectors to I/O | |||
DD BUFFER ; Data buffer | |||
On return, the original flags are still on the stack (put there by the INT | |||
instruction). This is necessary because return information is passed back in | |||
the current flags. Be sure to pop the stack to prevent uncontrolled growth. | |||
WARNING: IF DISK I/O HANDLED BY THIS INTERRUPT EXCEEDS THE LIMIT IMPOSED BY | |||
THE 64KB DIRECT MEMORY ACCESS BOUNDARY, UNPREDICTABLE RESULTS CAN OCCUR. WE | |||
RECOMMEND YOU CAREFULLY CHECK THE SECTOR SIZE AND THE NUMBER OF SECTORS TO BE | |||
READ OR WRITTEN TO BEFORE ISSUING THIS CALL. | |||
The number of sectors specified is transferred between the given drive and | |||
the transfer address. Logical sector numbers (LSN) are obtained by numbering | |||
each sector sequentially starting from track 0, head 0, sector 1 (logical | |||
sector 0) and continuing along the same head, then to the next head until the | |||
last sector on the last head of the track is counted. Thus, logical sector 1 | |||
is track 0, head 0, sector 2; logical sector 2 is track 0, head 0, sector 3; | |||
and so on. Numbering continues with sector 1 on head 0 of the next track. | |||
Note that although the sectors are sequentially numbered (for example, | |||
sectors 2 and 3 on track 0 in the example above), they may not be physically | |||
adjacent on the disk, because of interleaving. Note that the mapping is | |||
different from that used by DOS version 1.10 for dual-sided diskettes. | |||
All registers except the segment registers are destroyed by this call. If | |||
the transfer was successful, the carry flag (CF) is 0. If the transfer was | |||
not successful CF=1 and (AX) indicate the error as follows. (AL) is the DOS | |||
4.00 error code that is the same as the error code returned in the low byte | |||
of DI when an interrupt 24H is issued, and (AH) contains: | |||
80H Attachment failed to respond | |||
40H SEEK operation failed | |||
08H Bad CRC on diskette read | |||
04H Requested sector not found | |||
03H Write attempt on write-protected diskette | |||
02H Error other than types listed above | |||
WARNING: BEFORE ISSUING THIS INTERRUPT TO REMOVABLE MEDIA, THE MEDIA IN THE | |||
DRIVE MUST BE ESTABLISHED CORRECTLY. THIS CAN BE ACCOMPLISHED BY ISSUING | |||
EITHER AN INT 21H GENERIC IOCTL (AH=44H), WITH A REQUEST TO RETURN THE BPB | |||
THAT BUILD BPB RETURNS; OR AN INT 21H GET CURRENT DIRECTORY (AH=47H). | |||
27H TERMINATE BUT STAY RESIDENT | |||
This vector is used by programs that are to remain resident when COMMAND.COM | |||
regains control. | |||
DOS 4.00 function call 31H is the preferred method to cause a program to | |||
remain resident, because this allows return information to be passed. It | |||
allows a program larger than 64KB to remain resident. After initializing | |||
itself, the program must set DX to its last address plus one, relative to the | |||
program's initial DS or ES value (the offset at which other programs can be | |||
loaded), and then execute an interrupt 27H. DOS 4.00 then considers the | |||
program as an extension of itself, so the program is not overlaid when other | |||
programs are executed. This concept is useful for loading programs such as | |||
user-written interrupt handlers that must remain resident. | |||
NOTES: | |||
1. This interrupt must not be used by .EXE programs that are loaded into the | |||
high end of memory. | |||
2. This interrupt restores the interrupt 22H, 23H, and 24H vectors in the | |||
same manner as interrupt 20H. Therefore, it cannot be used to install | |||
permanently resident Ctrl-Break or critical error handler routines. | |||
3. The maximum size of memory that can be made resident by this method is | |||
64KB. | |||
4. Memory can be used more efficiently if the block containing a copy of the | |||
environment is deallocated before terminating. This can be done by | |||
loading ES with the segment contained in 2C of the PSP, and issuing | |||
function call 49H (Free Allocated Memory). | |||
5. DOS 4.00 function call 4CH allows the terminating program to pass a | |||
completion (or error) code to DOS 4.00, which can be interpreted within | |||
batch processing (see function call 31H). | |||
6. Terminate-but-stay-resident function calls do not automatically close | |||
files. | |||
28H-2EH RESERVED FOR DOS 4.00 | |||
These interrupts are reserved for DOS 4.00 use. | |||
2FH MULTIPLEX INTERRUPT | |||
Interrupt 2FH is the multiplex interrupt. A general interface is defined | |||
between two processes. The specific application using interrupt 2FH defines | |||
specific functions and parameters. | |||
Every multiplex interrupt handler is assigned a specific multiplex number. | |||
The multiplex number is specified in the AH register. The specific function | |||
that the handler is to perform is specified in the AL register. Other | |||
parameters are placed in the other registers, as needed. The handlers are | |||
chained into the interrupt 2FH interrupt vector. There is no defined method | |||
for assigning a multiplex number to a handler. You must pick one. To avoid | |||
a conflict if two applications choose the same multiplex number, the | |||
multiplex numbers used by an application should be patchable. | |||
The multiplex numbers AH=00H through BFH are reserved for DOS 4.00. | |||
Applications should use multiplex numbers C0H through FFH. | |||
NOTE: When in the chain for interrupt 2FH, if your code calls DOS 4.00 or if | |||
you execute with interrupts enabled, your code must be reentrant and | |||
recursive. | |||
Function Codes | |||
AH=1 | |||
AH=1 is the resident part of PRINT. | |||
The following table contains the function codes that you can specify in AL to | |||
request the resident portion of print to perform a specific function: | |||
+---------------------------------------------------------------------------+ | |||
| FUNCTION | | |||
| CODES DESCRIPTION | | |||
+---------------------------------------------------------------------------+ | |||
| 0 Get installed state | | |||
+---------------------------------------------------------------------------+ | |||
| 1 Submit file | | |||
+---------------------------------------------------------------------------+ | |||
| 2 Cancel file | | |||
+---------------------------------------------------------------------------+ | |||
| 3 Cancel all files | | |||
+---------------------------------------------------------------------------+ | |||
| 4 Status | | |||
+---------------------------------------------------------------------------+ | |||
| 5 End of status | | |||
+---------------------------------------------------------------------------+ | |||
Print Error Codes | |||
The following table contains the error codes that are returned from the | |||
resident portion of print. | |||
+---------------------------------------------------------------------------+ | |||
| ERROR | | |||
| CODES DESCRIPTION | | |||
+---------------------------------------------------------------------------+ | |||
| 1 Invalid function | | |||
+---------------------------------------------------------------------------+ | |||
| 2 File not found | | |||
+---------------------------------------------------------------------------+ | |||
| 3 Path not found | | |||
+---------------------------------------------------------------------------+ | |||
| 4 Too many open files | | |||
+---------------------------------------------------------------------------+ | |||
| 5 Access denied | | |||
+---------------------------------------------------------------------------+ | |||
| 6 Queue full | | |||
+---------------------------------------------------------------------------+ | |||
| 9 Busy | | |||
+---------------------------------------------------------------------------+ | |||
| 12 Name too long | | |||
+---------------------------------------------------------------------------+ | |||
| 15 Invalid drive | | |||
+---------------------------------------------------------------------------+ | |||
AL=0 Get Installed State | |||
This call must be defined by all interrupt 2FH handlers. It is used by the | |||
caller of the handler to determine if the handler is present. On entry, | |||
AL=0, AH=1. On return, AL contains the installed state as follows: | |||
AL=0 Not installed, permissible to install | |||
AL=1 Not installed, not permissible to install | |||
AL=FF Installed | |||
AL=1 Submit File | |||
On entry, AL=1, AH=1, and DS:DX points to the submit packet. A submit packet | |||
contains the level (BYTE) and a pointer to the ASCIIZ string (DWORD in offset | |||
segment form). The level value for DOS 4.00 is 0. The ASCIIZ string must | |||
contain the drive, path, and filename of the file you want to print. The | |||
filename cannot contain global filename characters. AL=2 Cancel File | |||
On entry, AL=2, AH=1, and DS:DX points to the ASCIIZ string for the print | |||
file you want to cancel. Global filename characters are allowed in the | |||
filename. AL=3 Cancel all Files | |||
On entry, AL=3 and AH=1. | |||
AL=4 Status | |||
This call holds the jobs in the print queue so that you can scan the queue. | |||
Issuing any other code releases the jobs. On entry, AL=4, AH=1. On return, | |||
DX contains the error count. The error count is the number of consecutive | |||
failures PRINT had while trying to output the last character. If there are | |||
no failures, the number is 0. DS:SI points to the print queue. The print | |||
queue consists of a series of filename entries. Each entry is 64 bytes long. | |||
The first entry in the queue is the file currently being printed. The end of | |||
the queue is marked by a queue entry having a null as the first character. | |||
AL=5 End of Status: Issue this call to release the queue from call 4. On | |||
entry, AL=5 and AH=1. On return, AX contains the error codes. For | |||
information on the error codes returned, refer to "Print Error Codes" on | |||
page A-10. | |||
AL=F8-FF Reserved by DOS 4.00 | |||
AH=6 | |||
AH=6 is the resident part of ASSIGN. | |||
The Get Installed State function | |||
(AL=0) is supported. | |||
AH=8H, 10H, 12H, 13H Reserved by DOS 4.00 | |||
AH=B7H | |||
AH=B7H is the resident part of APPEND. | |||
The Get Installed State function | |||
(AL=0) is supported. | |||
AL=2 Get APPEND version | |||
This call is for distinguishing between | |||
the PC LAN APPEND and the DOS 4.00 APPEND. | |||
On return, if AX=FFFFH then the DOS 4.00 | |||
APPEND is loaded. | |||
AL=4 Get APPEND Path Pointer | |||
(DOS 4.00 APPEND only) | |||
On return ES:DI points to the | |||
currently active APPEND path. | |||
AL=6 Get APPEND Function State | |||
(DOS 4.00 APPEND only) | |||
BX is returned with bits set indicating | |||
if APPEND is currently enabled and what | |||
functions are in effect. | |||
+--------+------------------------------------------------------------------+ | |||
| BIT | FUNCTION IN EFFECT IF BIT IS ON | | |||
+--------+------------------------------------------------------------------+ | |||
| 0 | APPEND enabled | | |||
+--------+------------------------------------------------------------------+ | |||
| 13 | /PATH | | |||
+--------+------------------------------------------------------------------+ | |||
| 14 | /E | | |||
+--------+------------------------------------------------------------------+ | |||
| 15 | /X | | |||
+--------+------------------------------------------------------------------+ | |||
NOTE: The functions in effect do not change whether or not APPEND is | |||
disabled. | |||
AL=7 Set function state (DOS 4.00 APPEND | |||
only) | |||
On input BX is the new setting for all functions. | |||
The suggested procedure is to get the current function | |||
state, turn on or turn off the desired bits, then | |||
use this call to set the function state. | |||
AL=11H Set Return Found Name State (DOS 4.00 APPEND | |||
only) | |||
On request AL=17, a process system state flag is set. If this flag is set, | |||
then on the next ASCIIZ 3DH, 43H or 6CH function call within Interrupt 21H | |||
that APPEND processes, APPEND returns the name it finds to the application | |||
filename buffer. This name may be different from the one the application | |||
offered. The application must provide enough space for the found name. | |||
After APPEND has processed an | |||
Interrupt 21H, it resets the Return Found Name state. An example of this | |||
process follows: | |||
MOV AH,0B7H ; Indicate APPEND | |||
MOV AL,0 ; Get installed state | |||
INT 2FH | |||
CMP AL,0 ; APPEND installed? | |||
JE NOT_INSTALLED | |||
MOV AH,0B7H ; Indicate APPEND | |||
MOV AL,2 ; Get APPEND version | |||
INT 2FH | |||
CMP AX,-1 ; DOS version? | |||
PC_LAN_APPEND ; AX<> -1 means PC LAN | |||
JNE | |||
APPEND | |||
; The following functions are valid only if DOS 4.00 APPEND | |||
MOV AH,0B7H ; Indicate APPEND | |||
MOV AL,4 ; Get APPEND path pointer | |||
INT 2FH | |||
; ES:DI = address of APPEND path | |||
; (Buffer is 128 characters long) | |||
MOV AH,0B7H ; Indicate APPEND | |||
MOV AL,6 ; Get function state | |||
INT 2FH | |||
; BX = function state | |||
; 8000H = /X is on | |||
; 4000H = /E is on | |||
; 2000H = /PATH is on | |||
; 0001H = APPEND enabled | |||
; If off, similar to null | |||
; APPEND path | |||
; Set on by any non-status | |||
; occurrence of APPEND | |||
MOV AH,0B7H ; Indicate APPEND | |||
MOV AL,7 ; Set function state | |||
MOV BX,state ; New state | |||
INT 2FH | |||
MOV AH,0B7H ; Indicate APPEND | |||
MOV AL,11H ; Set Return Found | |||
; Name state | |||
INT 2FH | |||
Example 2FH Handler | |||
MYNUM DB X ; X = The specific AH | |||
; multiplex number. | |||
INT 2F NEXT DD ? ; Chain location | |||
INT 2F: | |||
ASSUME DS:NOTHING,ES:NOTHING,SS:NOTHING | |||
CMP AH,MYNUM | |||
JE MINE | |||
JMP INT 2F NEXT ; Chain to next | |||
; 2FH Handler | |||
MINE: | |||
CMP AL,0F8H | |||
JB DO FUNC | |||
IRET ; IRET on reserved | |||
; functions | |||
DO FUNC: | |||
OR AL,AL | |||
JNE NON INSTALL ; Non Get Installed | |||
; State request | |||
MOV AL,0FFH ; Say I'm here | |||
IRET ; All done | |||
NON INSTALL: | |||
. | |||
. | |||
. | |||
Installing the Handler | |||
The following example contains the functions necessary to install a handler: | |||
MOV AH,MYNUM | |||
XOR AL,AL | |||
INT 2FH ; Ask if already | |||
; installed | |||
OR AL,AL | |||
JZ OK INSTALL | |||
BAD INSTALL: ; Handler already installed .sp 3 | |||
OK INSTALL: ; Install my | |||
; handler | |||
MOV AL,2FH | |||
MOV AH,GET INTERRUPT VECTOR | |||
INT 21H ; Get multiplex | |||
; vector | |||
MOV WORD PTR INT 2F NEXT+2,ES | |||
MOV WORD PTR INT 2F NEXT,BX | |||
MOV DX,OFFSET INT 2F | |||
MOV AL,2FH | |||
MOV AH,SET INTERRUPT VECTOR | |||
INT 21H ; Set multiplex | |||
; vector | |||
. | |||
. | |||
. | |||
30H-3FH RESERVED FOR DOS 4.00 | |||
These interrupts are reserved for DOS 4.00 use. | |||
</PRE> | |||
==Appendix B== | |||
<PRE> | |||
APPENDIX B. DOS 4.00 FUNCTION CALLS 100 | |||
Using DOS 4.00 Function Calls 219 | |||
Program Code Fragments 230 | |||
.COM Programs 236 | |||
DOS 4.00 Registers 256 | |||
Responding to Errors 340 | |||
Extended Error Codes 355 | |||
00H -- Program Terminate 518 | |||
01H -- Console Input with Echo 546 | |||
02H -- Display Output 581 | |||
03H -- Auxiliary Input 603 | |||
04H -- Auxiliary Output 631 | |||
05H -- Printer Output 655 | |||
06H -- Direct Console I/O 672 | |||
07H -- Direct Console Input Without Echo 720 | |||
08H -- Console Input Without Echo 753 | |||
09H -- Display String 786 | |||
0AH -- Buffered Keyboard Input 815 | |||
0BH -- Check Standard Input Status 848 | |||
0CH -- Clear Keyboard Buffer and Invoke a Keyboard Function 868 | |||
0DH -- Disk Reset 885 | |||
0EH -- Select Disk 904 | |||
0FH -- Open File 937 | |||
10H -- Close File 985 | |||
11H -- Search for First Entry 1022 | |||
12H -- Search for Next Entry 1099 | |||
13H -- Delete File 1149 | |||
14H -- Sequential Read 1193 | |||
15H -- Sequential Write 1240 | |||
16H -- Create File 1286 | |||
17H -- Rename File 1330 | |||
19H -- Current Disk 1380 | |||
1AH -- Set Disk Transfer Address 1400 | |||
1BH -- Allocation Table Information 1425 | |||
1CH -- Allocation Table Information for Specific Device 1453 | |||
21H -- Random Read 1489 | |||
22H -- Random Write 1541 | |||
23H -- File Size 1599 | |||
24H -- Set Relative Record Field 1642 | |||
25H -- Set Interrupt Vector 1668 | |||
26H -- Create New Program Segment 1695 | |||
27H -- Random Block Read 1725 | |||
28H -- Random Block Write 1787 | |||
29H -- Parse Filename 1847 | |||
2AH -- Get Date 1918 | |||
2BH -- Set Date 1946 | |||
2CH -- Get Time 1979 | |||
2DH -- Set Time 2015 | |||
2EH -- Set/Reset Verify Switch 2051 | |||
2FH -- Get Disk Transfer Address (DTA) 2085 | |||
30H -- Get DOS Version Number 2108 | |||
31H -- Terminate Process and Remain Resident 2138 | |||
33H -- Get/Set System Value 2175 | |||
35H -- Get Interrupt Vector 2235 | |||
36H -- Get Disk Free Space 2262 | |||
38H -- Get or Set Country Dependent Information 2318 | |||
39H -- Create Subdirectory (MKDIR) 2431 | |||
3AH -- Remove Subdirectory (RMDIR) 2466 | |||
3BH -- Change the Current Directory (CHDIR) 2498 | |||
3CH -- Create a File (CREAT) 2530 | |||
3DH -- Open a File 2577 | |||
3EH -- Close a File Handle 2812 | |||
3FH -- Read from a File or Device 2840 | |||
40H -- Write to a File or Device 2886 | |||
41H -- Delete a File from a Specified Directory (UNLINK) 2938 | |||
42H -- Move File Read Write Pointer (LSEEK) 2971 | |||
43H -- Change File Mode (CHMOD) 3035 | |||
44H -- I/O Control for Devices 3092 | |||
45H -- Duplicate a File Handle (DUP) 3103 | |||
46H -- Force a Duplicate of a Handle (FORCDUP) 3137 | |||
47H -- Get Current Directory 3170 | |||
48H -- Allocate Memory 3202 | |||
49H -- Free Allocated Memory 3237 | |||
4AH -- Modify Allocated Memory Blocks (SETBLOCK) 3263 | |||
4BH -- Load or Execute a Program (EXEC) 3303 | |||
4CH -- Terminate a Process (EXIT) 3442 | |||
4DH -- Get Return Code of a Subprocess (WAIT) 3466 | |||
4EH -- Find First Matching File (FIND FIRST) 3494 | |||
4FH -- Find Next Matching File (FIND NEXT) 3567 | |||
54H -- Get Verify Setting 3606 | |||
56H -- Rename a File 3628 | |||
57H -- Get/Set File's Date and Time 3669 | |||
59H -- Get Extended Error 3714 | |||
5AH -- Create Unique File 3785 | |||
5BH -- Create New File 3839 | |||
5CH -- Lock/Unlock File Access 3878 | |||
5E00H -- Get Machine Name 3972 | |||
5E02H -- Set Printer Setup 4006 | |||
5E03H -- Get Printer Setup 4051 | |||
5F02H -- Get Redirection List Entry 4096 | |||
5F03H -- Redirect Device 4169 | |||
5F04H -- Cancel Redirection 4259 | |||
62H -- Get Program Segment Prefix Address 4305 | |||
65H -- Get Extended Country Information 4328 | |||
66H -- Get/Set Global Code Page 4451 | |||
67H -- Set Handle Count 4494 | |||
68H -- Commit File 4539 | |||
6CH -- Extended Open/Create 4562 | |||
APPENDIX B. DOS 4.00 FUNCTION CALLS | |||
NUMBER FUNCTION NAME | |||
00H Program terminate | |||
01H Console input with echo | |||
02H Display output | |||
03H Auxiliary input | |||
04H Auxiliary output | |||
05H Printer output | |||
06H Direct console I/O | |||
07H Direct console input without echo | |||
08H Console input without echo | |||
09H Display string | |||
0AH Buffered keyboard input | |||
0BH Check standard input status | |||
0CH Clear keyboard buffer, invoke a keyboard function | |||
0DH Disk reset | |||
0EH Select disk | |||
0FH Open file | |||
10H Close file | |||
11H Search for first entry | |||
12H Search for next entry | |||
13H Delete file | |||
14H Sequential read | |||
15H Sequential write | |||
16H Create file | |||
17H Rename file | |||
18H Reserved by DOS 4.00 | |||
19H Current disk | |||
1AH Set disk transfer address | |||
1BH Allocation table information | |||
1CH Allocation table information for specific device | |||
1DH Reserved by DOS 4.00 | |||
1EH Reserved by DOS 4.00 | |||
1FH Reserved by DOS 4.00 | |||
20H Reserved by DOS 4.00 | |||
21H Random read | |||
22H Random write | |||
23H File size | |||
24H Set relative record field | |||
25H Set interrupt vector | |||
26H Create new program segment | |||
27H Random block read | |||
28H Random block write | |||
29H Parse filename | |||
2AH Get date | |||
2BH Set date | |||
2CH Get time | |||
2DH Set time | |||
2EH Set/reset verify switch | |||
2FH Get disk transfer address | |||
30H Get DOS 4.00 version number | |||
31H Terminate process and remain resident | |||
32H Reserved by DOS 4.00 | |||
33H Get/Set system value | |||
34H Reserved by DOS 4.00 | |||
35H Get interrupt vector | |||
36H Get disk free space | |||
37H Reserved by DOS 4.00 | |||
38H Get/set country dependent information | |||
39H Create subdirectory (MKDIR) | |||
3AH Remove subdirectory (RMDIR) | |||
3BH Change current directory (CHDIR) | |||
3CH Create a file (CREAT) | |||
3DH Open a file | |||
3EH Close a file handle | |||
3FH Read from a file or device | |||
40H Write to a file or device | |||
41H Delete a file from a specified directory (UNLINK) | |||
42H Move file read/write pointer (LSEEK) | |||
43H Change file mode (CHMOD) | |||
44H I/O control for devices (IOCtl) | |||
45H Duplicate a file handle (DUP) | |||
46H Force a duplicate of a file handle (FORCDUP) | |||
47H Get current directory | |||
48H Allocate memory | |||
49H Free allocated memory | |||
4AH Modify allocated memory blocks (SETBLOCK) | |||
4BH Load or execute a program (EXEC) | |||
4CH Terminate a process (EXIT) | |||
4DH Get return code of a subprocess (WAIT) | |||
4EH Find first matching file (FIND FIRST) | |||
4FH Find next matching file (FIND NEXT) | |||
50H Reserved by DOS 4.00 | |||
51H Reserved by DOS 4.00 | |||
52H Reserved by DOS 4.00 | |||
53H Reserved by DOS 4.00 | |||
54H Get verify setting | |||
55H Reserved by DOS 4.00 | |||
56H Rename a file | |||
57H Get/set a file's date and time | |||
58H Reserved for DOS 4.00 | |||
59H Get extended error | |||
5AH Create unique file | |||
5BH Create new file | |||
5CH Lock/unlock file access | |||
5DH Reserved by DOS 4.00 | |||
5E00H Get machine name | |||
5E02H Set printer setup | |||
5E03H Get printer setup | |||
5F02H Get redirection list entry | |||
5F03H Redirect device | |||
5F04H Cancel redirection | |||
60H Reserved by DOS 4.00 | |||
61H Reserved by DOS 4.00 | |||
62H Get PSP address | |||
63H Reserved by DOS 4.00 | |||
64H Reserved by DOS 4.00 | |||
65H Get extended country information | |||
66H Get/set global code page | |||
67H Set handle count | |||
68H Commit file | |||
69H Reserved by DOS 4.00 | |||
6AH Reserved | |||
6BH Reserved by DOS 4.00 | |||
6CH Extended open/create | |||
USING DOS 4.00 FUNCTION CALLS | |||
Most function calls require input to be passed to them in registers. After | |||
setting the appropriate register values, issue the function calls in either | |||
of the following ways: | |||
The preferred method is to place the function number in AH and issue | |||
interrupt 21H. | |||
Place the function number in AH and execute a call to offset 50H in your | |||
program segment prefix. | |||
PROGRAM CODE FRAGMENTS | |||
In each of the function call descriptions in this chapter, the input, output | |||
and method of use are described using a small program code fragment. These | |||
fragments are written in IBM PC Assembler Language. | |||
.COM PROGRAMS | |||
The descriptions assume that the program is an .EXE, not a .COM program. If | |||
a .COM program is desired, do not include either of the following | |||
instructions: | |||
MOV ES,SEG -- | |||
or | |||
MOV DS,SEG -- | |||
NOTES: | |||
1. Some FCB function calls do not permit invalid characters (0DH-29H). | |||
2. Device names cannot end in a colon. | |||
3. The contents of the AX register can be altered by any of the function | |||
calls. Even though no error code is returned in AX, it is possible that | |||
AX has been changed. | |||
DOS 4.00 REGISTERS | |||
DOS 4.00 uses the following registers, pointers, and flags when executing | |||
interrupts and function calls: | |||
+---------------------------------------------------------------------------+ | |||
| REGISTER GENERAL | | |||
| DEFINITION REGISTERS | | |||
+---------------------------------------------------------------------------+ | |||
| AX Accumulator (16-bit) | | |||
| AH Accumulator high-order byte (8-bit) | | |||
| AL Accumulator low-order byte (8-bit) | | |||
+---------------------------------------------------------------------------+ | |||
| BX Base (16-bit) | | |||
| BH Base high-order byte (8-bit) | | |||
| BL Base low-order byte (8-bit) | | |||
+---------------------------------------------------------------------------+ | |||
| CX Count (16-bit) | | |||
| CH Count high-order byte (8-bit) | | |||
| CL Count low-order byte (8-bit) | | |||
+---------------------------------------------------------------------------+ | |||
| DX Data (16-bit) | | |||
| DH Data high-order (8-bit) | | |||
| DL Data low-order (8-bit) | | |||
+---------------------------------------------------------------------------+ | |||
| Flags OF,DF,IF,TF,SF,ZF,AF,PF,CF | | |||
+---------------------------------------------------------------------------+ | |||
+---------------------------------------------------------------------------+ | |||
| REGISTER | | |||
| DEFINITION POINTERS | | |||
+---------------------------------------------------------------------------+ | |||
| SP Stack pointer (16-bit) | | |||
+---------------------------------------------------------------------------+ | |||
| BP Base pointer (16-bit) | | |||
+---------------------------------------------------------------------------+ | |||
| IP Instruction pointer (16-bit) | | |||
+---------------------------------------------------------------------------+ | |||
+---------------------------------------------------------------------------+ | |||
| REGISTER SEGMENT | | |||
| DEFINITION REGISTERS | | |||
+---------------------------------------------------------------------------+ | |||
| CS Code segment (16-bit) | | |||
+---------------------------------------------------------------------------+ | |||
| DS Data segment (16-bit) | | |||
+---------------------------------------------------------------------------+ | |||
| SS Stack segment (16-bit) | | |||
+---------------------------------------------------------------------------+ | |||
| ES Extra segment (16-bit) | | |||
+---------------------------------------------------------------------------+ | |||
+---------------------------------------------------------------------------+ | |||
| REGISTER INDEX | | |||
| DEFINITION REGISTERS | | |||
+---------------------------------------------------------------------------+ | |||
| DI Destination index (16-bit) | | |||
+---------------------------------------------------------------------------+ | |||
| SI Source index (16-bit) | | |||
+---------------------------------------------------------------------------+ | |||
Register Numbering Convention | |||
Each register is 16 bits long and is divided into a high and low byte. Each | |||
byte is 8 bits long. The bits are numbered from right to left. The low byte | |||
contains bits 0 through 7 and the high byte contains bits 8 through 15. The | |||
chart below shows the hexadecimal values assigned to each bit. | |||
+--------------------------------------------------------------------------+ | |||
| High Byte Low Byte | | |||
+--------------------------------------------------------------------------+ | |||
| Bit 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 | | |||
+--------------------------------------------------------------------------+ | |||
| Hex value 8 4 2 1 8 4 2 1 8 4 2 1 8 4 2 1 | | |||
+--------------------------------------------------------------------------+ | |||
DOS 4.00 Internal Stack | |||
When DOS 4.00 gains control, it switches to an internal stack. User | |||
registers are preserved unless information is passed back to the requester as | |||
indicated in the specific requests. The user stack needs to be sufficient to | |||
accommodate the interrupt system. It is recommended that the user stack be | |||
200H in addition to what the user needs. | |||
RESPONDING TO ERRORS | |||
Handle function calls report an error by setting the carry flag and returning | |||
the error code in AX. FCB function calls report an error by returning FFH in | |||
AL. | |||
Extended error support (59H) provides a common set of error codes and | |||
specific error information such as error classification, location, and | |||
recommended action. In most critical cases, applications can analyze the | |||
error code and take specific action. Recommended actions are intended for | |||
programs that do not understand the error codes. Programs can take advantage | |||
of extended error support both from interrupt 24H critical error handlers and | |||
after issuing interrupt 21H function calls. Do not code to specific error | |||
codes. | |||
EXTENDED ERROR CODES | |||
HEXADECIMAL DECIMAL | |||
CODE CODE MEANING | |||
01H 1 Invalid function number | |||
02H 2 File not found | |||
03H 3 Path not found | |||
04H 4 Too many open files (no handles left) | |||
05H 5 Access denied | |||
06H 6 Invalid handle | |||
07H 7 Memory control blocks destroyed | |||
08H 8 Insufficient memory | |||
09H 9 Invalid memory block address | |||
0AH 10 Invalid environment | |||
0BH 11 Invalid format | |||
0CH 12 Invalid access code | |||
0DH 13 Invalid data | |||
0EH 14 Reserved | |||
0FH 15 Invalid drive was specified | |||
10H 16 Attempt to remove the current directory | |||
11H 17 Not same device | |||
12H 18 No more files | |||
13H 19 Attempt to write on write-protected diskette | |||
14H 20 Unknown unit | |||
15H 21 Drive not ready | |||
16H 22 Unknown command | |||
17H 23 Cyclic redundancy check (CRC) -- part of diskette | |||
is bad | |||
18H 24 Bad request structure length | |||
19H 25 Seek error | |||
1AH 26 Unknown media type | |||
1BH 27 Sector not found | |||
1CH 28 Printer out of paper | |||
1DH 29 Write fault | |||
1EH 30 Read fault | |||
1FH 31 General failure | |||
20H 32 Sharing violation | |||
21H 33 Lock violation | |||
22H 34 Invalid disk change | |||
23H 35 FCB unavailable | |||
24H 36 Sharing buffer overflow | |||
25H 37 Reserved by DOS 4.00 | |||
26H 38 Unable to complete file operation | |||
27H-31H 39-49 Reserved by DOS 4.00 | |||
50H 80 File exists | |||
51H 81 Reserved | |||
52H 82 Cannot make directory entry | |||
53H 83 Fail on INT 24 | |||
54H 84 Too many redirections | |||
55H 85 Duplicate redirection | |||
56H 86 Invalid password | |||
57H 87 Invalid parameter | |||
58H 88 Network data fault | |||
59H 89 Function not supported by network | |||
HEXADECIMAL DECIMAL | |||
CODE CODE MEANING | |||
5AH 90 Required system component not installed | |||
Extended Error Codes | |||
HEXADECIMAL DECIMAL | |||
CODE CODE MEANING | |||
32H 50 Network request not supported | |||
33H 51 Remote computer not listening | |||
34H 52 Duplicate name on network | |||
35H 53 Network path not found | |||
36H 54 Network busy | |||
37H 55 Network device no longer exists | |||
38H 56 NETBIOS command limit exceeded | |||
39H 57 System error; NETBIOS error | |||
3AH 58 Incorrect response from network | |||
3BH 59 Unexpected network error | |||
3CH 60 Incompatible remote adapter | |||
3DH 61 Print queue full | |||
3EH 62 Not enough space for print file | |||
3FH 63 Print file was cancelled | |||
40H 64 Network name was deleted | |||
41H 65 Access denied | |||
42H 66 Network device type incorrect | |||
43H 67 Network name not found | |||
44H 68 Network name limit exceeded | |||
45H 69 NETBIOS session limit exceeded | |||
46H 70 Sharing temporarily paused | |||
47H 71 Network request not accepted | |||
48H 72 Print or disk redirection is paused | |||
49H-4FH 73-79 Reserved | |||
Error Classes | |||
HEXADECIMAL DECIMAL | |||
VALUE VALUE DESCRIPTION | |||
01H 1 OUT OF RESOURCE: Example: out of space or | |||
channels. | |||
02H 2 TEMPORARY SITUATION: Something expected to | |||
disappear with time. This is not an error | |||
condition, but a temporary situation such as a | |||
locked file. | |||
03H 3 AUTHORIZATION: Permission problem. | |||
04H 4 INTERNAL: Internal error in system software. | |||
Probable problem with system software rather than a | |||
user or system failure. | |||
HEXADECIMAL DECIMAL | |||
VALUE VALUE DESCRIPTION | |||
05H 5 HARDWARE FAILURE: A serious problem not the fault | |||
of user program. | |||
06H 6 SYSTEM FAILURE: Serious failure of system software | |||
not the fault of the user, such as missing or | |||
incorrect configuration files. | |||
07H 7 APPLICATION PROGRAM ERROR: Inconsistent requests. | |||
08H 8 NOT FOUND: File or item not found. Inconsistent | |||
requests. | |||
09H 9 BAD FORMAT: File or value in invalid format or | |||
type; unsuitable. | |||
0AH 10 LOCKED: Locked file or item. | |||
0BH 11 MEDIA: Media failure such as incorrect disk, CRC | |||
error, or defective media. | |||
0CH 12 ALREADY EXISTS: Duplication error, such as | |||
declaring a machine name that already exists. | |||
0DH 13 UNKNOWN: Classification does not exist or is | |||
inappropriate. | |||
Actions | |||
HEXADECIMAL DECIMAL | |||
CODE CODE DESCRIPTION | |||
01H 1 RETRY: Retry a few times, then prompt user to | |||
determine if the program should continue or be | |||
terminated. | |||
02H 2 DELAY RETRY: Retry several times after pause, then | |||
prompt user to determine if the program should | |||
continue or be terminated. | |||
03H 3 USER: If the input was entered by a user, advise | |||
reentry. The error, however, may have occurred in | |||
the program itself, such as a bad drive letter or | |||
bad filename specification. | |||
04H 4 ABORT: Abort application with cleanup. The | |||
application cannot proceed, but the system is in an | |||
orderly state and it is safe to stop the | |||
application. | |||
05H 5 IMMEDIATE EXIT: Stop application immediately | |||
without clearing registers. Do not use the | |||
application to close files or update indexes, but | |||
exit as soon as possible. | |||
06H 6 IGNORE: Ignore. | |||
07H 7 RETRY AFTER USER INTERVENTION: The user needs to | |||
perform some action such as removing a diskette and | |||
inserting a different one. Then retry the | |||
operation. | |||
Locus (Location) | |||
HEXADECIMAL DECIMAL | |||
VALUE VALUE DESCRIPTION | |||
01H 1 UNKNOWN: Not specific; not appropriate. | |||
02H 2 BLOCK DEVICE: Related to random access mass disk | |||
storage. | |||
03H 3 NET: Related to the network. | |||
04H 4 SERIAL DEVICE: Related to serial devices. | |||
05H 5 MEMORY: Related to random access memory. | |||
00H -- | |||
PROGRAM TERMINATE | |||
PURPOSE | |||
Stops the execution of a program. | |||
EXAMPLE | |||
MOV AH,00H ; Function Call -- Terminate Program | |||
INT 21H ; Issue request to DOS | |||
; No return | |||
COMMENTS | |||
The terminate, Ctrl-Break, and critical error exit addresses are restored to | |||
the values they had on entry to the terminating program, from the values | |||
saved in the program segment prefix. All file buffers are flushed and the | |||
handles opened by the process are closed. Any files that have changed in | |||
length and not closed are not recorded properly in the directory. Control | |||
transfers to the terminate address. This call performs exactly the same | |||
function as interrupt 20H. It is the program's responsibility to ensure that | |||
the CS register contains the segment address of its program segment prefix | |||
control block before calling this function. | |||
Function 4CH -- Terminate a Process is the preferred method for ending a | |||
program. | |||
01H -- | |||
CONSOLE INPUT WITH ECHO | |||
PURPOSE | |||
Waits for a character to be read at the standard input device (unless one is | |||
ready), then echoes the character to the standard output device and returns | |||
the character in AL. | |||
EXAMPLE | |||
MOV AH,01H ; Function Call -- keyboard input | |||
INT 21H ; Issue request to DOS | |||
MOV Char,AL ; Save character | |||
CMP AL,0 ; Extended character ? | |||
JNE Normal Char ; No! | |||
MOV AH,01H ; Function Call -- keyboard input | |||
INT 21H ; Issue request to DOS | |||
MOV ExtChar,AL ; Save extended character | |||
Normal Char: | |||
Character LABEL WORD ; Complete character | |||
Char DB ? ; Character buffer | |||
ExtChar DB ? ; Character buffer | |||
COMMENTS | |||
The character is checked for a Ctrl-Break. If Ctrl-Break is detected, an | |||
interrupt 23H is executed. | |||
For function call 01H, extended ASCII codes require two function calls. The | |||
first call returns 00H as an indicator that the next call will return an | |||
extended code. | |||
02H -- | |||
DISPLAY OUTPUT | |||
PURPOSE | |||
Outputs the character in DL to the standard output device. | |||
EXAMPLE | |||
MOV AH,02H ; Function Call -- Display Output | |||
MOV DL,Char ; Get character to display | |||
INT 21H ; Issue request to DOS | |||
CHAR DB ? ; Character buffer | |||
COMMENTS | |||
If the character in DL is a backspace (08), the cursor is moved left one | |||
position (nondestructive). If a Ctrl-Break is detected after the output, an | |||
interrupt 23H is executed. | |||
03H -- | |||
AUXILIARY INPUT | |||
PURPOSE | |||
Waits for a character from the standard auxiliary device, then returns that | |||
character in AL. | |||
EXAMPLE | |||
MOV AH,03H ; Function Call -- Auxiliary Input | |||
INT 21H ; Issue request to DOS | |||
MOV Char,AL ; Save character | |||
CHAR DB ? ; Character buffer | |||
COMMENTS | |||
Auxiliary (AUX) support is unbuffered and noninterrupt driven. | |||
At startup, DOS 4.00 initializes the first auxiliary port to 2400 baud, no | |||
parity, one-stop bit, and 8-bit word. | |||
The auxiliary function calls (03H and 04H) do not return status or error | |||
codes. For greater control, you should use the ROM BIOS routine (interrupt | |||
14H) or write an AUX device driver and use IOCtl. | |||
04H -- | |||
AUXILIARY OUTPUT | |||
PURPOSE | |||
Outputs the character in DL to the standard auxiliary device. | |||
EXAMPLE | |||
MOV AH,04H ; Function Call -- Auxiliary Output | |||
MOV DL,Char ; Get character to output | |||
INT 21H ; Issue request to DOS | |||
; Nothing returned | |||
CHAR DB ? ; Character buffer | |||
COMMENTS | |||
If the character in DL is a backspace (08), the cursor is moved left one | |||
position (nondestructive). If a Ctrl-Break is detected after the output, an | |||
interrupt 23H is executed. | |||
05H -- | |||
PRINTER OUTPUT | |||
PURPOSE | |||
Outputs the character in DL to the standard printer device. | |||
EXAMPLE | |||
MOV AH,05H ; Function Call -- Printer Output | |||
MOV DL,Char ; Get character to output | |||
INT 21H ; Issue request to DOS | |||
; Nothing returned | |||
CHAR DB ? ; Character buffer | |||
06H -- | |||
DIRECT CONSOLE I/O | |||
PURPOSE | |||
Gets a character from the standard input device if one is ready, or outputs a | |||
character to the standard output device. | |||
EXAMPLES | |||
In loop: | |||
MOV AH,06H ; Function Call -- Direct Console I/O | |||
MOV DL,-1 ; 0FFH for input | |||
INT 21H ; Issue request to DOS | |||
JZ In loop ; No character yet on input | |||
MOV Char,AL ; Save character | |||
CMP AL,0 ; Extended Character ? | |||
JNE Normal Char ; No! | |||
MOV AH,07H ; Function Call -- Keyboard Input | |||
INT 21H ; Issue request to DOS | |||
MOV ExtChar,AL ; Save extended character | |||
Normal Char: | |||
or | |||
MOV AH,06H ; Function Call -- Direct Console I/O | |||
MOV DL,Char ; Get character to display (not 0FFH) | |||
INT 21H ; Issue request to DOS | |||
Character LABEL WORD ; Complete character | |||
Char DB ? ; Character buffer | |||
ExtChar DB ? ; Character buffer | |||
COMMENTS | |||
If DL is FFH, AL returns with the 0 flag clear and an input character from | |||
the standard input device, if one is ready. If a character is not ready, the | |||
0 flag will be set. | |||
If DL is not FFH, DL is assumed to have a valid character that is output to | |||
the standard output device. This function does not check for Ctrl-Break, or | |||
Ctrl-PrtSc. | |||
For function call 06H, extended ASCII codes require two function calls. The | |||
first call returns 00H as an indicator that the next call will return an | |||
extended code. | |||
07H -- | |||
DIRECT CONSOLE INPUT WITHOUT ECHO | |||
PURPOSE | |||
Waits for a character to be read at the standard input device (unless one is | |||
ready), then returns the character in AL. | |||
EXAMPLE | |||
MOV AH,07H ; Function Call -- Direct Console Input (no echo) | |||
INT 21H ; Issue request to DOS | |||
MOV Char,AL ; Save character | |||
CMP AL,0 ; Extended character ? | |||
JNE Normal Char ; No! | |||
MOV AH,07H ; Function Call -- Direct Console Input (no echo) | |||
INT 21H ; Issue request to DOS | |||
MOV ExtChar,AL ; Save extended character | |||
Normal Char: | |||
Character LABEL WORD ; Complete character | |||
Char DB ? ; Character buffer | |||
ExtChar DB ? ; Character buffer | |||
COMMENTS | |||
As with function call 06H, no checks are made on the character. | |||
For function call 07H, extended ASCII codes require two function calls. The | |||
first call returns 00H as an indicator that the next call will return an | |||
extended code. | |||
08H -- | |||
CONSOLE INPUT WITHOUT ECHO | |||
PURPOSE | |||
Waits for a character to be read at the standard input device (unless one is | |||
ready) and returns the character in AL. | |||
EXAMPLE | |||
MOV AH,08H ; Function Call -- Console Input (no echo) | |||
INT 21H ; Issue request to DOS | |||
MOV Char,AL ; Save character | |||
CMP AL,0 ; Extended character ? | |||
JNE Normal Char; No! | |||
MOV AH,08H ; Function Call -- Console Input (no echo) | |||
INT 21H ; Issue request to DOS | |||
MOV ExtChar,AL ; Save extended character | |||
Normal Char: | |||
Character LABEL WORD ; Complete character | |||
Char DB ? ; Character buffer | |||
ExtChar DB ? ; Character buffer | |||
COMMENTS | |||
The character is checked for Ctrl-Break. If Ctrl-Break is detected, an | |||
interrupt 23H is executed. | |||
For function call 08H, extended ASCII codes require two function calls. The | |||
first call returns 00H as an indicator that the next call will return an | |||
extended code. | |||
09H -- | |||
DISPLAY STRING | |||
PURPOSE | |||
Sends the characters in the string to the standard output device. | |||
EXAMPLE | |||
MOV AX,SEG String | |||
MOV DS,AX ;Set DS:DX to string | |||
MOV DX,OFFSET String | |||
MOV AH,09H ;Function Call - Display String | |||
INT 21H ;Issue request to DOS | |||
String DB "This string ends at the first Dollar" | |||
DB 0DH,0AH | |||
DB "$" | |||
COMMENTS | |||
The character string in memory must be terminated by a $ (24H). Each | |||
character in the string is output to the standard output device in the same | |||
form as function call 02H. | |||
ASCII codes 0DH and 0AH represent carriage return and line feed, | |||
respectively. | |||
0AH -- | |||
BUFFERED KEYBOARD INPUT | |||
PURPOSE | |||
Reads characters from the standard input device and places them in the buffer | |||
beginning at the third byte. | |||
EXAMPLE | |||
MOV AX,SEG Buffer | |||
MOV DS,AX ;Set DS:DX to return Buffer | |||
MOV DX,OFFSET Buffer | |||
MOV AH,0AH ;Function Call-Buffered | |||
;Keyboard Input | |||
INT 21H ;Issue request to DOS | |||
Buffer DB 128 ; Max length of input | |||
CurLen DB ? ; Number of characters input | |||
; (excludes Return (0DH)) | |||
CurText DB 128 DUP(?) ; Up to 128 characters allowed | |||
COMMENTS | |||
The first byte of the input buffer specifies the number of characters the | |||
buffer can hold. This value cannot be 0. Reading the standard input device | |||
and filling the buffer continues until Enter is read. If the buffer fills to | |||
one less than the maximum number of characters it can hold, each additional | |||
character read is ignored and causes the bell to ring, until Enter is read. | |||
The second byte of the buffer is set to the number of characters received, | |||
excluding the carriage return (0DH), which is always the last character. | |||
0BH -- | |||
CHECK STANDARD INPUT STATUS | |||
PURPOSE | |||
Checks if there is a character available from the standard input device. | |||
EXAMPLE | |||
In LOOP: | |||
MOV AH,0BH ; Function Call -- Check Input | |||
INT 21H ; Issue request to DOS | |||
CMP AL,-1 ; 0FFH indicates character available | |||
JNE In LOOP: | |||
COMMENTS | |||
If a character is available from the STDIN device, AL is FFH. Otherwise, AL | |||
is undefined. If a Ctrl-Break is detected, an interrupt 23H is executed. | |||
0CH -- | |||
CLEAR KEYBOARD BUFFER AND INVOKE A KEYBOARD FUNCTION | |||
PURPOSE | |||
Clears the standard input device of any characters, then executes the | |||
function call number in AL. | |||
EXAMPLE | |||
MOV AH,0CH ; Function Call -- Clear keyboard & | |||
; Invoke function | |||
MOV AL,Function ; Function Call to execute | |||
; (only 01H, 06H, 07H, 08H, and 0AH are allowed). | |||
INT 21H ; Issue request to DOS | |||
; Output depends on Function Call selected | |||
0DH -- | |||
DISK RESET | |||
PURPOSE | |||
Writes to the disk file buffers that have been modified. All buffers are | |||
then made available for reuse. | |||
EXAMPLE | |||
MOV AH,0DH ; Function Call -- Disk Reset | |||
INT 21H ; Issue request to DOS | |||
; No return | |||
COMMENTS | |||
It is necessary to close or commit all open files to correctly update the | |||
disk directory. | |||
0EH -- | |||
SELECT DISK | |||
PURPOSE | |||
Selects the drive specified in DL (0=A, 1=B, etc.) (if valid) as the default | |||
drive. | |||
EXAMPLE | |||
MOV AH,0EH ; Function Call -- Select Disk | |||
MOV DL,Drive ; Drive to select (0=A:, 1=B:, ...) | |||
INT 21H ; Issue request to DOS | |||
MOV LastDrive,AL : Save max drive number (1=A:, 2=B:, ...) | |||
MOV AH,19H ; Function Call -- Get Current Disk | |||
INT 21H ; Issue request to DOS | |||
CMP AL,DL ; Selected drive = requested | |||
JNE Error ; No, Error! | |||
Drive DB ; New Drive to select | |||
LastDrive DB ; Highest Valid Drive | |||
COMMENTS | |||
The total number of unique drive letters, including diskette and fixed disk | |||
drives, that can be referenced is returned in AL. The value in AL is equal | |||
to the value of LASTDRIVE in CONFIG.SYS or the total number of installed | |||
devices, whichever is greater. For DOS 4.00 5 is the minimum value returned | |||
in AL. If the system has only one diskette drive, it is counted as two to be | |||
consistent with the philosophy of thinking of the system as having logical | |||
drives A and B. | |||
0FH -- | |||
OPEN FILE | |||
PURPOSE | |||
Searches the current directory for the named file and AL returns FFH if it is | |||
not found. If the named file is found, AL returns 00H and the FCB is filled | |||
as described below. | |||
EXAMPLE | |||
MOV AX,SEG FCB ;Address FCB Parameter Block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,0FH ;Function Call-FCB Open | |||
INT 21H ;Issue request to DOS | |||
FCB LABEL BYTE | |||
Drive DB 0 ; Drive (0=Current, 1=A, 2=B, ...) | |||
FName DB "FILENAME" ; File Name (blank padded) | |||
Ext DB "EXT" ; File Extension (blank padded) | |||
DB 25 DUP(0) ; Filled in by DOS 4.00 | |||
COMMENTS | |||
AL is 00H if the file is opened. | |||
AL is FFH if the file was not opened. | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. | |||
If the drive code was 0 (default drive), it is changed to the actual drive | |||
used (1=A, 2=B, and so on). This allows changing the default drive without | |||
interfering with subsequent operations on this file. The current block field | |||
(FCB bytes C-D) is set to 0. The size of the record to be worked with (FCB | |||
bytes E-F) is set to the system default of 80H. The size of the file and the | |||
date are set in the FCB from information obtained from the directory. You | |||
can change the default value for the | |||
record size (FCB bytes E-F) or set the random record size and/or current | |||
record field. Perform these actions after the open, but before any disk | |||
operations. | |||
The file is opened in compatibility mode. For information on compatibility | |||
mode, refer to function call 3DH. | |||
10H -- | |||
CLOSE FILE | |||
PURPOSE | |||
Closes a file. | |||
EXAMPLE | |||
MOV AX,SEG FCB ; Address FCB Parameter Block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,10H ; Function Call-FCB Close | |||
INT 21H ; Issue request to DOS | |||
CMP AL,0 ; File Closed? | |||
JNE Error ; No, Error! | |||
FCB LABEL BYTE | |||
; Contents set by previous operations | |||
COMMENTS | |||
AL is 00H if the file is closed. | |||
AL is FFH if the file was not closed. | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. | |||
This function call must be executed on open files after file writes, and we | |||
highly recommend that it be used on all files. If the file is not found in | |||
its correct position in the current directory, it is assumed the disk was | |||
changed and AL returns FFH. Otherwise, the directory is updated to reflect | |||
the status in the FCB, the buffers for that file are flushed, and AL returns | |||
00H. | |||
11H -- | |||
SEARCH FOR FIRST ENTRY | |||
PURPOSE | |||
Searches the current directory for the first matching filename. | |||
EXAMPLE | |||
MOV AX,SEG DTA ; Address Buffer for found file | |||
MOV DS,AX ; information | |||
MOV DX,OFFSET DTA | |||
MOV AH,1AH ; Function Call-Set DTA address | |||
INT 21H ; Issue request to DOS | |||
MOV AX,SEG FCB ; Address FCB parameter block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,11H ; Function Call-FCB search first | |||
INT 21H ; Issue request to DOS | |||
CMP AL,0 ; File found? | |||
JNE Error ; No, Error! | |||
FCB LABEL BYTE | |||
Fdrive DB 0 ; Drive (0=Current, 1=A, 2=B, ...) | |||
Fname DB "FILENAME" ; File name (blank padded, may use ?) | |||
Fext DB "EXT" ; File extension (blank padded, may use ?) | |||
DB 25 DUP(0) ; Filled in by DOS | |||
DTA LABEL BYTE | |||
Ddrive DB ? ; Drive | |||
Dname DB "????????" ; File Name (blank padded) | |||
Dext DB "???" ; File Extension (blank padded) | |||
DB 25 DUP(0) ; Filled in by DOS 4.00 | |||
COMMENTS | |||
AL is 00H if the file is found. | |||
AL is FFH if the file was not found. | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. | |||
The current disk directory is searched for the first matching filename. If | |||
none are found, AL returns FFH. Global filename characters are allowed in | |||
the filename and extension. If a matching filename is found, AL returns 00H | |||
and the locations at the disk transfer address are set as follows: | |||
If the FCB provided for searching was an extended FCB, the first byte at | |||
the disk transfer address is set to FFH followed by 5 bytes of 0, then | |||
the attribute byte from the search FCB, then the drive number used (1=A, | |||
2=B, etc.), then the 32 bytes of the directory entry. Thus, the disk | |||
transfer address contains a valid unopened extended FCB with the same | |||
search attributes as the search FCB. | |||
If the FCB provided for searching was a standard FCB, then the first byte | |||
is set to the drive number used (1=A, 2=B), and the next 32 bytes contain | |||
the matching directory entry. Thus, the disk transfer address contains a | |||
valid unopened normal FCB. | |||
NOTES: | |||
If an extended FCB is used, the following search pattern is used: | |||
1. If the attribute is 0, only normal file entries are found. Entries for | |||
volume label, sub-directories, hidden and system files, are not returned. | |||
2. If the attribute field is set for hidden or system files, or directory | |||
entries, it is an inclusive search. All normal file entries, plus all | |||
entries matching the specified attributes, are returned. To look at all | |||
directory entries except the volume label, the attribute byte may be set | |||
to hidden + system + directory (all 3 bits on). | |||
3. If the attribute field is set for the volume label, it is considered an | |||
exclusive search, and only the volume label entry is returned. | |||
12H -- | |||
SEARCH FOR NEXT ENTRY | |||
PURPOSE | |||
Searches the current directory for the next matching filename. | |||
EXAMPLE | |||
MOV AX,SEG DTA ; Address Buffer for found file | |||
MOV DS,AX ; Information | |||
MOV DX,OFFSET DTA | |||
MOV AH,1AH ; Function Call-Set DTA address | |||
INT 21H ; Issue request to DOS | |||
MOV AX,SEG FCB ; Address FCB Parameter Block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,12H ; Function Call-FCB Search Next | |||
INT 21H ; Issue request to DOS | |||
CMP AL,0 ; File found? | |||
JNE Error ; No, Error! | |||
FCB LABEL BYTE | |||
; As set by FCB Search First | |||
DTA LABEL BYTE | |||
Drive DB ? ; Drive | |||
Fname DB "????????" ; File Name (blank padded) | |||
Ext DB "???" ; File Extension (blank padded) | |||
DB 25 DUP(0) ; Filled in by DOS 4.00 | |||
COMMENTS | |||
AL is 00H if the file is found. | |||
AL is FFH if the file was not found. | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. | |||
After a matching filename has been found using function call 11H, function | |||
12H may be called to find the next match to an ambiguous request. | |||
The DTA contains information from the previous Search First or Search Next. | |||
All of the FCB, except for the name/extension field, is used to keep | |||
information necessary for continuing the search, so no disk operations may be | |||
performed if this FCB is between a previous function 11H or 12H call and this | |||
one. | |||
13H -- | |||
DELETE FILE | |||
PURPOSE | |||
Deletes all current directory entries that match the specified filename. The | |||
specified filename cannot be read-only. | |||
EXAMPLE | |||
MOV AX,SEG FCB ;Address FCB Parameter Block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,13H ;Function Call-FCB Delete File | |||
INT 21H ;Issue request to DOS | |||
CMP AL,0 ;File(s) Deleted? | |||
JNE Error ;No, Error! | |||
FCB LABEL BYTE | |||
Drive DB 0 ; Drive | |||
FName DB Filename ; File Name (blank padded, may | |||
Ext DB Ext ; File Extension (blank padded, may | |||
DB 25 DUP(0) ; Filled in by DOS | |||
COMMENTS | |||
AL is 00H if the file is found. | |||
AL is FFH if the file was not found. | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. | |||
All matching current directory entries are deleted. The global filename | |||
character "?" is allowed in the filename or extension. If no directory | |||
entries match, AL returns FFH; otherwise AL returns 00H. | |||
If the file is specified in read-only mode, the file is not deleted. | |||
NOTE: Close open files before deleting them. | |||
Network Access Rights: Requires Create access rights. | |||
14H -- | |||
SEQUENTIAL READ | |||
PURPOSE | |||
Loads the record addressed by the current block (FCB bytes C-D) and the | |||
current record (FCB byte 1F) at the disk transfer address (DTA), then the | |||
record address is increased. | |||
EXAMPLE | |||
MOV AX,SEG DTA ;Address Data buffer | |||
MOV DS,AX | |||
MOV DX,OFFSET DTA | |||
MOV AH,1AH ;Function call Set DTA Address | |||
INT 21H ;Issue request to DOS | |||
MOV AX,SEG FCB ;Address FCB Parameter Block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,14H ;Function Call-FCB Sequential Read | |||
INT 21H ;Issue request to DOS | |||
CMP AL,0 ;Data Read? | |||
JNE Error ;No, Error! | |||
FCB LABEL BYTE | |||
; Set by previous open | |||
DTA LABEL BYTE | |||
DB ?Dup(0) ;I/O buffer | |||
COMMENTS | |||
AL is 00H if the read was successful. | |||
AL is 01H if the file was at End of File (EOF). | |||
AL is 02H if the read would have caused a wrap or overflow because the DTA | |||
was too small (the read was not completed). | |||
AL is 03H if EOF (a partial record was read and filled out with 0's). | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. The length of the record is determined by the FCB record size | |||
field. | |||
Network Access Rights: Requires Read access rights. | |||
15H -- | |||
SEQUENTIAL WRITE | |||
PURPOSE | |||
Writes the record addressed by the current block and record fields (size | |||
determined by the FCB record size field) from the disk transfer address. If | |||
records are less than the sector size, the record is buffered for an eventual | |||
write when a sector's worth of data is accumulated. Then the record address | |||
is increased. | |||
EXAMPLE | |||
MOV AX,SEG DTA ;Address Data buffer | |||
MOV DS,AX | |||
MOV DX,OFFSET DTA | |||
MOV AH,1AH ;Function Set DTA Address | |||
INT 21H ;Issue request to DOS | |||
MOV AX,SEG FCB ;Address FCB Parameter Block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,15H ;Function Call-FCB Sequential Write | |||
INT 21H ;Issue request to DOS | |||
CMP AL,0 ;Data Written? | |||
JNE Error ;No, Error! | |||
FCB LABEL BYTE | |||
; Set by previous open | |||
DTA LABEL BYTE | |||
DB ?Dup(0) ;I/O buffer | |||
COMMENTS | |||
AL is 00H if the write was successful. | |||
AL is 01H if the disk or diskette is full (write cancelled). | |||
AL is 02H if the write would have caused a wrap or overflow because the DTA | |||
was too small (write cancelled). | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. If the file is specified in read-only mode, the sequential write | |||
is not performed and 01H is returned in AL. | |||
Network Access Rights: Requires Write access rights. | |||
16H -- | |||
CREATE FILE | |||
PURPOSE | |||
Creates a new file. | |||
EXAMPLE | |||
MOV AX,SEG FCB ;Address FCB parameter block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,16H ;Function Call-FCB create file | |||
INT 21H ;Issue request to DOS | |||
CMP AL,0 ;File created and opened? | |||
JNE Error ;No, Error! | |||
FCB LABEL BYTE | |||
Fdrive DB 0 ; Drive (0=Current, 1=A, 2=B, ...) | |||
Fname DB "FILENAME" ; File name (blank padded) | |||
Fext DB "EXT" ; File extension (blank padded) | |||
DB 25 DUP(0) ; Filled in by DOS | |||
COMMENTS | |||
AL is 00H if the file is created and opened. | |||
AL is FFH if the file was not created (normally a full directory or disk | |||
full). | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. | |||
If a matching entry is found it is reused. If no match is found, the | |||
directory is searched for an empty entry. If a match is found, the entry is | |||
initialized to a 0-length file, the file is opened (see function call 0FH), | |||
and AL returns 00H. | |||
The file may be marked hidden during its creation by using an extended FCB | |||
containing the appropriate attribute byte. | |||
Network Access Rights: Requires Create access rights. | |||
17H -- | |||
RENAME FILE | |||
PURPOSE | |||
Changes every matching occurrence of the first filename in the current | |||
directory of the specified drive to the second, with the restriction that two | |||
files cannot have the same name and extension. | |||
EXAMPLE | |||
MOV AX,SEG FCB ;Address FCB Parameter Block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,17H ;Function Call-FCB Rename File | |||
INT 21H ;Issue request to DOS | |||
CMP AL,0 ;File(s) Renamed? | |||
JNE Error ;No, Error! | |||
FCB LABEL BYTE | |||
Fdrive DB 0 ; Drive (0=Current, 1=A, 2=B, ...) | |||
Fname DB "FILENAME" ; File Name (blank padded, may use ? | |||
Fext DB "EXT" ; File Extension (blank padded, may use ? | |||
DB 5 DUP(0) ; Reserved | |||
NewName DB "FILENAME" ; New File Name (blank padded, may use ? | |||
NewExt DB "EXT" ; New File Extension (blank padded, may use ? | |||
DB 7 DUP(0) ; Reserved | |||
COMMENTS | |||
AL is 00H if the file or files were renamed. | |||
AL is FFH if a file in the current directory did not match or the new name | |||
already exists. | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. | |||
The modified FCB has a drive code and filename in the usual position, and a | |||
second filename on the sixth byte after the first (DS:DX+11H) in what is | |||
normally a reserved area. | |||
If "?"s appear in the second name, the corresponding positions in the | |||
original name are unchanged. | |||
If the file is specified in read-only mode, the file is not renamed. | |||
Network Access Rights: Requires Create access rights. | |||
19H -- | |||
CURRENT DISK | |||
PURPOSE | |||
Determines the current default drive. | |||
EXAMPLE | |||
MOV AH,19H ; Function Call -- Get Current Disk | |||
INT 21H ; Issue request to DOS | |||
MOV Disk,AL ; Save Current Disk | |||
Disk DB ? ; Current Disk code (0=A:, 1=B:, ...) | |||
COMMENTS | |||
AL returns with the code of the current default drive (0=A, 1=B, and | |||
others.). | |||
1AH -- | |||
SET DISK TRANSFER ADDRESS | |||
PURPOSE | |||
Sets the disk transfer address to DS:DX. | |||
EXAMPLE | |||
MOV AX,SEG DTA ;Address Buffer | |||
MOV DS,AX | |||
MOV DX,OFFSET DTA | |||
MOV AH,1AH ;Function Call-Set DTA address | |||
INT 21H ;Issue request to DOS | |||
DTA LABEL BYTE ; Data Buffer | |||
COMMENTS | |||
The area defined by this call is from the address in DS:DX to the end of the | |||
segment in DS. DOS 4.00 does not allow disk transfers to wrap around within | |||
the segment, or overflow into the next segment. If you do not set the DTA, | |||
the default DTA is offset 80H in the program segment prefix. To get the DTA, | |||
issue function call 2FH. | |||
1BH -- | |||
ALLOCATION TABLE INFORMATION | |||
PURPOSE | |||
Returns information about the allocation table for the default drive. | |||
EXAMPLE | |||
MOV AH,1BH ; Function Call -- Allocation Table | |||
; Information | |||
INT 21H ; Issue request to DOS | |||
MOV NumAllocUnits,DX ; Save Number of Allocation Units | |||
MOV NumSectsAllocUnit,AL ; Save Number of Sectors/Allocation Unit | |||
MOV SectSize,CX ; Save of Sector Size | |||
MOV WORD PTR MediaType@+0,BX; Save Pointer to Media Type Byte | |||
MOV WORD PTR MediaType@+2,DS | |||
NumAllocUnits DW ? ; Number of Allocation Units on Current | |||
NumSectsAllocUnit DB ? ; Number Sectors in an Allocation Unit | |||
SectSize DW ? ; Sector Size | |||
MediaType@ DD ? ; Pointer to Media Type byte | |||
COMMENTS | |||
Refer to function call 36H (Get Disk Free Space). | |||
1CH -- | |||
ALLOCATION TABLE INFORMATION FOR SPECIFIC DEVICE | |||
PURPOSE | |||
Returns allocation table information for a specific device. | |||
EXAMPLE | |||
MOV AH,1CH ; Function Call -- | |||
; Allocation Table Information | |||
MOV DL,Drive ; Drive requested (0=current, | |||
; 1=A:, ...) | |||
INT 21H ; Issue request to DOS | |||
MOV NumAllocUnits,DX ; Save Number of Allocation Units | |||
MOV NumSectsAllocUnit,AL ; Save Number of Sectors/Allocation Unit | |||
MOV SectSize,CX ; Save of Sector Size | |||
MOV WORD PTR MediaType@+0,BX ; Save Pointer to Media Type Byte | |||
MOV WORD PTR MediaType@+2,DS | |||
Drive DB ; drive number to get info for | |||
NumAllocUnits DW ? ; Number of Allocation Units | |||
; on specified drive | |||
NumSectsAllocUnit DB ? ; Number Sectors in an | |||
; Allocation Unit | |||
SectSize DW ? ; Sector Size | |||
MediaType@ DD ? ; Pointer to Media Type byte | |||
COMMENTS | |||
This call is the same as call 1BH, except that on entry DL contains the | |||
number of the drive that contains the needed information (0 = default, 1 = A, | |||
and so forth.). For more information on DOS 4.00 disk allocation, refer to | |||
"The Disk Directory" on page 2-3. Also, refer to function call 36H (Get Disk | |||
Free Space). | |||
21H -- | |||
RANDOM READ | |||
PURPOSE | |||
Reads the record addressed by the current block and current record fields | |||
into memory at the current disk transfer address. | |||
EXAMPLE | |||
;Set up FCB | |||
MOV AX,SEG DTA ;Address Data buffer | |||
MOV DS,AX | |||
MOV DX,OFFSET DTA | |||
MOV AH,1AH ;Function Set DTA Address | |||
INT 21H ;Issue request to DOS | |||
MOV AX,SEG FCB ;Address FCB Parameter Block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,21H ;Function Call-FCB Random Read | |||
INT 21H ;Issue request to DOS | |||
CMP AL,0 ;Data Read? | |||
JNE Error ;No, Error! | |||
FCB LABEL BYTE | |||
; Set by previous open | |||
; DTA label byte | |||
COMMENTS | |||
AL is 00H if the read was successful. | |||
AL is 01H if the file was at End of File (EOF) (no data read). | |||
AL is 02H if the read would have caused a wrap or overflow because the DTA | |||
was too small (the read was not completed). | |||
AL is 03H if EOF (a partial record was read and filled out with 0's). | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. | |||
The current block and current record fields are set to agree with the random | |||
record field. The record addressed by these fields is read into memory at | |||
the current disk transfer address. For information on record size see | |||
Chapter 4, "Accessing Files Using File Control Blocks" on page 4-1. | |||
NOTE: Function 24H must be called before using this function. | |||
Network Access Rights: Requires Read access rights. | |||
22H -- | |||
RANDOM WRITE | |||
PURPOSE | |||
Writes the record addressed by the current block and current record fields | |||
from the current disk transfer address. | |||
EXAMPLE | |||
;Set up FCB | |||
MOV AX,SEG FCB ;Address FCB parameter block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,24H ;Function Call--FCB Set | |||
;Relative record field | |||
INT 21H ;Issue request to DOS | |||
MOV AX,SEG DTA ;Address data buffer | |||
MOV DS,AX | |||
MOV DX,OFFSET DTA | |||
MOV AH,1AH ;Function Set DTA address | |||
INT 21H ;Issue request to DOS | |||
MOV AX,SEG FCB ;Address FCB parameter block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,22H ;Function Call-FCB random writers | |||
INT 21H ;Issue request to DOS | |||
CMP AL,0 ;Data written? | |||
JNE Error ;No, error! | |||
FCB LABEL BYTE | |||
; Set by previous open | |||
DTA LABEL BYTE | |||
COMMENTS | |||
AL is 00H if the write was successful. | |||
AL is 01H if the write or diskette is full (write cancelled). | |||
AL is 02H if the read would have caused a wrap or overflow because the DTA | |||
was too small (write cancelled). | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. | |||
The current block and current record fields are set to agree with the random | |||
record field. Then the record addressed by these fields is written (or in | |||
the case of records not the same as sector sizes -- buffered) from the disk | |||
transfer address. | |||
If the file is specified in read-only mode, the random write is not | |||
performed. | |||
Network Access Rights: Requires Write access rights. | |||
23H -- | |||
FILE SIZE | |||
PURPOSE | |||
Searches the current directory for an entry that matches the specified file | |||
and sets the FCBs random record field to the number of records in the file. | |||
EXAMPLE | |||
MOV AX,SEG FCB ; Address FCB parameter block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,23H ; Function Call-FCB file size | |||
INT 21H ; Issue request to DOS | |||
CMP AL,0 ; File found? | |||
JNE Error ; No, error! | |||
FCB LABEL BYTE | |||
Drive DB 0 ; Drive (0=Current, 1=A, 2=B, ...) | |||
Name DB "FILENAME" ; File name (blank padded) | |||
Ext DB "EXT" ; File extension (blank padded) | |||
DB 25 DUP(0) ; Filled in by DOS | |||
COMMENTS | |||
AL is 00H if the file exists. | |||
AL is FFH if the file was not created (normally a full directory or disk | |||
full). | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. | |||
The directory is searched for the matching entry. If a matching entry is | |||
found, the random record field is set to the number of records in the file | |||
(in terms of the record size field rounded up). If no matching entry is | |||
found, AL returns FFH. | |||
NOTE: If you do not set the FCB record size field before using this | |||
function, incorrect information is returned. | |||
24H -- | |||
SET RELATIVE RECORD FIELD | |||
PURPOSE | |||
Sets the random record field to the same file address as the current block | |||
and record fields. | |||
EXAMPLE | |||
MOV AX,SEG FCB ;Address FCB parameter block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,24H ;Function Call--FCB set | |||
;Relative record field | |||
INT 21H ;Issue request to DOS | |||
FCB LABEL BYTE | |||
; Set by previous open | |||
COMMENTS | |||
You must call this function before you perform random reads and writes, and | |||
random block reads and writes. | |||
25H -- | |||
SET INTERRUPT VECTOR | |||
PURPOSE | |||
Sets the interrupt vector table for the interrupt number. | |||
EXAMPLE | |||
MOV AX,SEG Handler ;Address new handler | |||
MOV DS,AX | |||
MOV DX,OFFSET Handler | |||
MOV AH,25H ;Function Call - Set Interrupt | |||
;Vector | |||
MOV AL,Vector | |||
INT 21H ;Issue request to DOS | |||
Vector DB ? ;Number of vector to be replaced | |||
Handler: ;Code to process interrupt | |||
COMMENTS | |||
The interrupt vector table for the interrupt number specified in AL is set to | |||
address contained in DS:DX. Use function call 35H (Get Interrupt Vector) to | |||
obtain the contents of the interrupt vector. | |||
26H -- | |||
CREATE NEW PROGRAM SEGMENT | |||
PURPOSE | |||
Creates a new program segment. | |||
EXAMPLE | |||
MOV AH,26H ; Function Call -- Create Program | |||
; Segment | |||
MOV DX,SEG PSP ; Segment address to create new PSP | |||
INT 21H ; Issue request to DOS | |||
PSP LABEL BYTE ; Area to fill in | |||
DB 100H DUP(0) | |||
COMMENTS | |||
The entire 100H area at location 0 in the current program segment is copied | |||
into location 0 in the new program segment. The memory size information at | |||
location 6 in the new segment is updated and the current termination, | |||
Ctrl-Break exit and critical error addresses from interrupt vector table | |||
entries for interrupts 22H, 23H, and 24H are saved in the new program segment | |||
starting at 0AH. They are restored from this area when the program ends. | |||
NOTE: The EXEC function call 4BH provides a more complete service. | |||
Therefore, you should use the EXEC 4BH and avoid using this call. | |||
27H -- | |||
RANDOM BLOCK READ | |||
PURPOSE | |||
Reads the specified number of records (in terms of the record size field) | |||
from the file address specified by the random record field into the disk | |||
transfer address. | |||
EXAMPLE | |||
;Set up disk transfer address | |||
MOV AX,SEG DTA ;Address data buffer | |||
MOV DS,AX | |||
MOV DX,OFFSET DTA | |||
MOV AH,1AH ;Function set DTA address | |||
INT 21H ;Issue request to DOS | |||
MOV AX,SEG FCB ;Address FCB parameter block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,24H ;Function Call -- FCB Set | |||
;Relative Record Field | |||
INT 21H ;Issue request to DOS | |||
MOV AX,SEG FCB ;Address FCB parameter block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV CX,Records to read ;number of records to read | |||
MOV AH,27H ;Function Call - FCB random block read | |||
INT 21H ;Issue request to DOS | |||
CMP AL,0 ;Data read? | |||
JNE Error ;No, error! | |||
FCB LABEL BYTE | |||
; Set by previous open | |||
DTA LABEL BYTE | |||
DB ?Dup(0) ;I/O buffer | |||
Records to read DW ? | |||
COMMENTS | |||
AL is 00H if the read was successful. | |||
AL is 01H if the file was at End of File (EOF) (no data read). | |||
AL is 02H if the read would have caused a wrap or overflow because the DTA | |||
was too small (the read was not completed.). | |||
AL is 03H if EOF (a partial record was read and filled out with zeros). | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. | |||
The random record field and the current block/record fields are set to | |||
address the next record (the first record not read). | |||
NOTE: Function 24H must be called before using this function. | |||
Network Access Rights: Requires Read access rights. | |||
28H -- | |||
RANDOM BLOCK WRITE | |||
PURPOSE | |||
Writes the specified number of records from the disk transfer address into | |||
the file address specified by the random record field. | |||
EXAMPLE | |||
;Set up disk transfer address | |||
MOV AX,SEG DTA ;Address data buffer | |||
MOV DS,AX | |||
MOV DX,OFFSET DTA | |||
MOV AH,1AH ;Function set DTA address | |||
INT 21H ;Issue request to DOS | |||
MOV AX,SEG FCB ;Address FCB parameter block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV AH,24H ;Function Call--FCB set | |||
;Relative record field | |||
INT 21H ;Issue request to DOS | |||
MOV AX,SEG FCB ;Address FCB parameter block | |||
MOV DS,AX | |||
MOV DX,OFFSET FCB | |||
MOV CX,Records to write ;Number of records to write | |||
MOV AH,28H ;Function Call - FCB Random Block write | |||
INT 21H ;Issue request to DOS | |||
CMP AL,0 ;Data written? | |||
JNE Error ;No, error! | |||
DTA LABEL BYTE | |||
DB ?DUP(0) ; I/O Buffer | |||
COMMENTS | |||
AL is 00H if the write was successful. | |||
AL is 01H if the disk or diskette is full (write cancelled). | |||
AL is 02H if the write would have caused a wrap or overflow because the DTA | |||
was too small (write cancelled). | |||
Use Function Call 59H (Get Extended Error) to determine the actual error | |||
condition. | |||
If there is insufficient space on the disk, AL returns 01H and no records are | |||
written. If CX is 0 upon entry, no records are written, but the file is set | |||
to the length specified by the random record field, whether longer or shorter | |||
than the current file size. (Allocation units are released or allocated as | |||
appropriate.) | |||
NOTE: Function call 24H must be called before using this function. | |||
Network Access Rights: Requires Write access rights. | |||
29H -- | |||
PARSE FILENAME | |||
PURPOSE | |||
Parses the specified filename. | |||
EXAMPLE | |||
MOV AX,SEG CmdBuf | |||
MOV DS,AX ;Address command string | |||
MOV SI,OFFSET CmdBuf | |||
MOV AX,SEG FCB | |||
MOV ES,AX ;Address FCB Parameter Block | |||
MOV DI,OFFSET FCB | |||
MOV AH,29H ;Function Call - FCB Parse Filename | |||
MOV AL,OPTIONS ;Set desired action | |||
INT 21H ;Issue request to DOS | |||
CMP AL,-1 ;Drive valid? | |||
JE Error ;No, Error! | |||
CmdBuf LABEL BYTE | |||
DB " a:file.ext ",0DH | |||
FCB LABEL BYTE | |||
; Created in a pre-open state based on input found. | |||
Options DB ? ;parsing options | |||
COMMENTS | |||
The contents of AL are used to determine the action to take, as shown below: | |||
<must = 0> | |||
bit: 7 6 5 4 3 2 1 0 | |||
If bit 0 = 1, leading separators are scanned off the command line at DS:SI. | |||
Otherwise, no scan-off of leading separators takes place. | |||
If bit 1 = 1, the drive ID byte in the FCB will be set (changed) only if a | |||
drive was specified in the command line being parsed. | |||
If bit 2 = 1, the filename in the FCB will be changed only if the command | |||
line contains a filename. | |||
If bit 3 = 1, the filename extension in the FCB will be changed only if the | |||
command line contains a filename extension. | |||
Filename separators include the following characters: | |||
: . : , = + along with TAB and SPACE. Filename terminators include all of | |||
these characters plus ,<, >, |, /, ', [, ], and any control characters. | |||
Output: | |||
AL is 00H if no global characters (? or *) were found in the Command String. | |||
AL is 01H if global characters (? or *) were found in the Command String. | |||
AL is FFH if the drive specified is invalid. | |||
The command line is parsed for a filename of the form d:filename.ext, and if | |||
found, a corresponding unopened FCB is created at ES:DI. If no drive | |||
specifier is present, it is assumed to be all blanks. If the character * | |||
appears in the filename or extension, it and all remaining characters in the | |||
name or extension are set to ?. | |||
DS:SI returns pointing to the first character after the filename and ES:DI | |||
points to the first byte of the formatted FCB. If no valid filename is | |||
present, ES:DI+1 contains a blank. | |||
2AH -- | |||
GET DATE | |||
PURPOSE | |||
Returns the day of the week, the year, month and date. | |||
EXAMPLE | |||
MOV AH,2AH ; Function Call -- Get Date | |||
INT 21H ; Issue request to DOS | |||
MOV DayofWeek,AL ; Save Day of the Week | |||
MOV Year,CX ; Save Year | |||
MOV Month,DH ; Save Month | |||
MOV Day,DL ; Save Day | |||
DayofWeek DB ? ; 0=Sunday, ... 6=Saturday | |||
Year DW ? ; 1980 to 2099 | |||
Month DB ? ; 1 to 12 | |||
Day DB ? ; 1 to 31 | |||
COMMENTS | |||
If the time-of-day clock rolls over to the next day, the date is adjusted | |||
accordingly, taking into account the number of days in each month and leap | |||
years. | |||
2BH -- | |||
SET DATE | |||
PURPOSE | |||
Sets the date (also sets CMOS clock, if present). | |||
EXAMPLE | |||
MOV AH,2BH ; Function Call -- Set Date | |||
MOV CX,Year ; Set Year | |||
MOV DH,Month ; Set Month | |||
MOV DL,Day ; Set Day | |||
INT 21H ; Issue request to DOS | |||
CMP AL,0 ; Valid Date? | |||
JNE Error ; No! | |||
Year DW ? ; 1980 to 2099 | |||
Month DB ? ; 1 to 12 | |||
Day DB ? ; 1 to 31 | |||
COMMENTS | |||
AL is 00H if the date is valid and the operation is successful. | |||
AL is FFH if the date is not valid. | |||
On entry, CX:DX must have a valid date in the same format as returned by | |||
function call 2AH. | |||
On return, AL returns 00H if the date is valid and the set operation is | |||
successful. AL returns FFH if the date is not valid. | |||
2CH -- | |||
GET TIME | |||
PURPOSE | |||
Returns the time; hours, minutes, seconds and hundredths of seconds. | |||
EXAMPLE | |||
MOV AH,2CH ; Function Call -- | |||
; Get Time | |||
INT 21H ; Issue request to DOS | |||
MOV Hour,CH ; Save Hour | |||
MOV Minute,CL ; Save Minute | |||
MOV Second,DH ; Save Second | |||
MOV Hundredth,DL ; Save Partial Second | |||
Hour DB ? ; 0 to 23 | |||
Minute DB ? ; 0 to 59 | |||
Second DB ? ; 0 to 59 | |||
Hundredth DB ? ; 0 to 99 | |||
COMMENTS | |||
On entry, AH contains 2CH. On return, CX:DX contains the time-of-day. Time | |||
is actually represented as four 8-bit binary quantities as follows: | |||
CH Hours (0-23) | |||
CL Minutes (0-59) | |||
DH Seconds (0-59) | |||
DL 1/100 seconds (0-99). | |||
This format is readily converted to a printable form yet can also be used for | |||
calculations, such as subtracting one time value from another. | |||
2DH -- | |||
SET TIME | |||
PURPOSE | |||
Sets the time (also sets the CMOS clock, if present). | |||
EXAMPLE | |||
MOV AH,2DH ; Function Call -- Set Time | |||
MOV CH,Hour ; Sst Hour | |||
MOV CL,Minute ; Set Minute | |||
MOV DH,Second ; Set Second | |||
MOV DL,Hundredth ; Set Partial Second | |||
INT 21H ; Issue request to DOS | |||
CMP AL,0 ; Valid Time? | |||
JNE Error ; No! | |||
Hour DB ? ; 0 to 23 | |||
Minute DB ? ; 0 to 59 | |||
Second DB ? ; 0 to 59 | |||
Hundredth DB ? ; 0 to 99 | |||
COMMENTS | |||
AL is 00H if the time is valid. | |||
AL is FFH if the time is not valid. | |||
On entry, CX:DX has time in the same format as returned by function 2CH. On | |||
return, if any component of the time is not valid, the set operation is | |||
cancelled and AL returns FFH. If the time is valid, AL returns 00H. | |||
If your system has a CMOS realtime clock, it will be set. | |||
2EH -- | |||
SET/RESET VERIFY SWITCH | |||
PURPOSE | |||
Sets the verify switch. | |||
EXAMPLE | |||
; To set VERIFY=OFF | |||
MOV AH,2EH ; Function Call -- Set | |||
; VERIFY | |||
MOV AL,0 ; Set OFF | |||
INT 21H ; Issue request to DOS | |||
; To set VERIFY=ON | |||
MOV AH,2EH ; Function Call -- Set | |||
; VERIFY | |||
MOV AL,1 ; Set ON | |||
INT 21H ; Issue request to DOS | |||
COMMENTS | |||
On entry, AL must contain 01H to turn verify on, or 00H to turn verify off. | |||
When verify is on, DOS 4.00 performs a verify operation each time it performs | |||
a disk write to assure proper data recording. Although disk recording errors | |||
are very rare, this function has been provided for applications in which you | |||
may wish to verify the proper recording of critical data. You can obtain the | |||
current setting of the verify switch through function call 54H. | |||
NOTE: Verification is not supported on data written to a network disk. | |||
2FH -- | |||
GET DISK TRANSFER ADDRESS (DTA) | |||
PURPOSE | |||
Returns the current disk transfer address. | |||
EXAMPLE | |||
MOV AH,2FH ; Function Call -- Get | |||
; DTA Address | |||
INT 21H ; Issue request to DOS | |||
MOV WORD PTR DTA@+0,BX ; Save Address | |||
MOV WORD PTR DTA@+2,ES | |||
DTA@ DD ? ; DTA Buffer | |||
COMMENTS | |||
On entry, AH contains 2FH. On return, ES:BX contains the current Disk | |||
Transfer Address. You can set the DTA using function call 1AH. | |||
30H -- | |||
GET DOS VERSION NUMBER | |||
PURPOSE | |||
Returns the DOS version number. | |||
EXAMPLE | |||
PUSH CX ; CX and BX destroyed in call | |||
PUSH BX | |||
MOV AH,30H ; Function Call -- Get DOS 4.00 | |||
; Version | |||
INT 21H ; Issue request to DOS | |||
MOV MajorVersion,AL ; Save Version | |||
MOV MinorVersion,AH | |||
POP BX | |||
POP CX | |||
MajorVersion DB ? ; X of X.YY | |||
MinorVersion DB ? ; YY of X.YY | |||
COMMENTS | |||
On entry, AH contains 30H. On return, BX and CX are set to 0. AL contains | |||
the major version number. AH contains the minor version number. | |||
If AL returns a major version number of 0, you can assume that the DOS | |||
version is pre-DOS 2.00. | |||
31H -- | |||
TERMINATE PROCESS AND REMAIN RESIDENT | |||
PURPOSE | |||
Terminates the current process and attempts to set the initial allocation | |||
block to the memory size in paragraphs. | |||
EXAMPLE | |||
MOV AH,31H ; Function Call -- Terminate | |||
; and Keep Process | |||
MOV AL,RetCode ; Set value of ERRORLEVEL | |||
MOV DX,MySize ; Set my program and data size | |||
INT 21H ; Issue request to DOS | |||
INT 20H ; Be safe if on DOS 4.00 Version 1.X | |||
RetCode DB ? ; Value to return to my EXEC'er | |||
MySize DW ? ; Size of my code and data | |||
; (in paragraphs) | |||
COMMENTS | |||
On entry, AL contains a binary return code. DX contains the memory size | |||
value in paragraphs. This function call does not free up any other | |||
allocation blocks belonging to that process. Files opened by the process are | |||
not closed when the call is executed. The return code passed in AL is | |||
retrievable by the parent through Wait (function call 4DH) and can be tested | |||
through the ERRORLEVEL batch subcommands. | |||
Memory is used efficiently if the block containing a copy of the environment | |||
is deallocated before terminating. This can be done by loading ES with the | |||
segment contained in 2C of the PSP, and issuing function call 49H (Free | |||
Allocated Memory). The five standard handles, 0000 through 0004, should be | |||
closed before exiting. | |||
33H -- | |||
GET/SET SYSTEM VALUE | |||
PURPOSE | |||
Set or get the state of System Values such as BREAK (Ctrl-Break checking). | |||
EXAMPLE | |||
; To check BREAK state | |||
MOV AH,33H ; Function Call -- Get/Set | |||
; System value | |||
MOV AL,0 ; Do Get BREAK | |||
INT 21H ; Issue request to DOS | |||
MOV BREAK,DL ; Save state | |||
; To set BREAK=OFF | |||
MOV AH,33H ; Function Call -- Get/Set | |||
; System value | |||
MOV AL,1 ; Do Set BREAK | |||
MOV DL,0 ; Set OFF | |||
INT 21H ; Issue request to DOS | |||
; To set BREAK=ON | |||
MOV AH,33H ; Function Call -- Get/Set | |||
; System Value | |||
MOV AL,1 ; Do Set BREAK | |||
MOV DL,1 ; Set ON | |||
INT 21H ; Issue request to DOS | |||
; To get the Boot Drive | |||
MOV AH,33H ; Function Call -- Get/Set | |||
; System Value | |||
MOV AL,5 ; Do Get Boot Drive | |||
INT 21H ; Issue request to DOS | |||
MOV Drive,DL ; Save boot drive | |||
BREAK DB ? ; Current BREAK state (0=OFF, 1=ON) | |||
Drive DB ? ; DOS 4.00 boot drive | |||
COMMENTS | |||
For BREAK: | |||
AL contains 00H to request the current state of Ctrl-Break checking. On | |||
return DL contains the current state (00H = OFF, 01H = ON). | |||
AL contains 01H to set the state. DL contains the new state (00H = OFF, 01H | |||
= ON). | |||
For boot drive: | |||
AL contains 05H to request the boot drive. On return DL contains the drive | |||
(A:=1, C:=3, ...). | |||
35H -- | |||
GET INTERRUPT VECTOR | |||
PURPOSE | |||
To obtain the address in an interrupt vector. | |||
EXAMPLE | |||
MOV AH,35H ; Function Call -- | |||
; Set Interrupt Vector | |||
MOV AL,Vector ; Vector to get (0 to 255) | |||
INT 21H ; Issue request to DOS | |||
MOV WORD PTR OldVect+0,BX | |||
MOV WORD PTR OldVect+2,ES | |||
OldVect DD ? ; Previous vector contents | |||
Vector DB ? ; Vector number to get | |||
COMMENTS | |||
On entry, AH contains 35H. AL contains a hexadecimal interrupt number. On | |||
return, ES:BX contains the CS:IP interrupt vector for the specified | |||
interrupt. Use function call 25H (Set Interrupt Vector) to set the interrupt | |||
vectors. | |||
36H -- | |||
GET DISK FREE SPACE | |||
PURPOSE | |||
Returns the disk free space (available clusters, clusters/drive, | |||
bytes/sector). | |||
EXAMPLE | |||
MOV AH,36H ; Function Call -- | |||
; Get disk free space | |||
MOV DL,Drive ; Drive to query | |||
; (0=current, 1=A:, | |||
; 2=B:, ...) | |||
INT 21H ; Issue request to DOS | |||
CMP AX,-1 ; Error? | |||
JE Error ; Yes | |||
MOV SectAU,AX ; Save allocation unit | |||
; Size | |||
MOV AvailAU,BX ; Save free allocation | |||
; Units | |||
MOV SectSize,CX ; Save sector size | |||
MOV TotalAU,DX ; Save disk size | |||
MOV AX,SectSize ; Calculate allocation | |||
; Unit size | |||
MUL SectAU | |||
MOV CX,AX ; CX = bytes/AU | |||
MOV AX,TotalAU ; Calculate total space | |||
MUL CX | |||
MOV WORD PTR TotalBytes+0,AX ; Save it | |||
MOV WORD PTR TotalBytes+2,DX | |||
MOV AX,AvailAU ; Calculate free space | |||
MUL CX | |||
MOV WORD PTR FreeBytes+0,AX ; Save it | |||
MOV WORD PTR FreeBytes+2,DX | |||
SectAU DW ? ; Sectors in an | |||
; Allocation unit | |||
AvailAU DW ? ; Free allocation units | |||
SectSize DW ? ; Bytes in a sector | |||
TotalAU DW ? ; Number of allocation | |||
; Units on DL disk | |||
TotalBytes DD ? ; Disk size in bytes | |||
FreeBytes DD ? ; Free space in bytes | |||
Drive DD ? ; Drive number to get info for | |||
COMMENTS | |||
If the drive number in DL was valid, BX contains the number of available | |||
allocation units, DX contains the total number of allocation units on the | |||
drive, CX contains the number of bytes per sector, and AX contains the number | |||
of sectors for each allocation unit. | |||
38H -- | |||
GET OR SET COUNTRY DEPENDENT INFORMATION | |||
PURPOSE | |||
Sets the Active Country or returns country dependent information. | |||
EXAMPLE | |||
; To set the Current Country | |||
MOV AH,38H ; Function Call -- Get/Set | |||
; Country Information | |||
MOV AL,CountryID ; Country ID (-1 if >= 255) | |||
MOV BX,CountryIDX ; Country ID (if AL=-1) | |||
MOV DX,-1 ; Indicate set country code | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
; To get Country Information | |||
MOV AX,SEG Buffer | |||
MOV DS,AX | |||
MOV DX,OFFSET Buffer | |||
MOV AH,38H | |||
MOV AL,CountryID ; Country ID (-1 if >= 255) | |||
; (0 to get current country) | |||
MOV BX,CountryIDX ; Country ID (if AL=-1) | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV CountryCode,BX ; Save current Country Code | |||
CountryCode DW ? ; Current country code | |||
CountryIDX DW ? ; Extended country code for input | |||
Buffer LABEL WORD ; Country information (see format below) | |||
CountryID DB ? ; Country code for input | |||
COUNTRY INFORMATION | |||
DateFormat DW ? ; Date Format: | |||
; 0 = m d y order | |||
; 1 = d m y order | |||
; 2 = y m d order | |||
$Symbol DB "????",0 ; Currency Symbol | |||
; example: "DM",0,?,? | |||
Sep1000 DB "?",0 ; Thousands Separator | |||
; example: ",",0 | |||
Sep1 DB "?",0 ; Fractions Separator | |||
; example: ".",0 | |||
SepDate DB "?",0 ; Date Separator | |||
; example: "/",0 | |||
SepTime DB "?",0 ; Time Separator | |||
; example: ":",0 | |||
$Format DB ? ; Currency Format: | |||
; 0 = currency symbol, value | |||
; 1 = value, currency symbol | |||
; 2 = currency symbol, space, value | |||
; 3 = value, space, currency symbol | |||
; 4 = currency symbol is decimal separat | |||
SigDigits DB ? ; Number of Significant Digits in Currency | |||
TimeFormat DB ? ; Time Format: | |||
; 0 = 12 hour clock | |||
; 1 = 24 hour clock | |||
UpperCaseAL@ DD ? ; Address of Routine to Upper Case AL | |||
; Only for values >=80H | |||
SepData DB "?",0 ; Data List Separator | |||
; example: ",",0 | |||
Reserved DW 5 DUP(?) ; Reserved for future | |||
COMMENTS | |||
The date format has the following values and meaning: | |||
CODE DATE | |||
0=USA m d y | |||
1=EUROPE d m y | |||
2=JAPAN y m d | |||
Case Map Call Address: The register contents for the case map call are: | |||
+---------------------------------------------------------------------------+ | |||
| ON REGISTER | | |||
| ENTRY CONTENTS | | |||
+---------------------------------------------------------------------------+ | |||
| AL ASCII code of character to be converted to uppercase | | |||
+---------------------------------------------------------------------------+ | |||
+---------------------------------------------------------------------------+ | |||
| ON REGISTER | | |||
| RETURN CONTENTS | | |||
+---------------------------------------------------------------------------+ | |||
| AL ASCII code of the uppercase input character | | |||
+---------------------------------------------------------------------------+ | |||
The case map call address is in a form suitable for a FAR call indirect. | |||
RETURNS | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. Function Call 65H, (Get Extended Country Information), returns | |||
more country information and is preferred. | |||
Setting the Current County Code by using this function call is not | |||
recommended. The user can set it by placing a COUNTRY command in the | |||
CONFIG.SYS file. The Country Code set by the user should not be changed. | |||
The NLSFUNC DOS 4.00 extension must be installed to change the Current | |||
Country. | |||
39H -- | |||
CREATE SUBDIRECTORY (MKDIR) | |||
PURPOSE | |||
Creates the specified directory. | |||
EXAMPLE | |||
MOV AX,SEG DName ;Directory Name | |||
MOV DS,AX | |||
MOV DX,OFFSET DName | |||
MOV AH,39H ;Function-Make a directory | |||
INT 21H ;Issue request to DOS | |||
JC Error | |||
DName DB "?? .. ??",0 ; ASCIIZ Name | |||
; Example: | |||
; "c:\dir",0 | |||
COMMENTS | |||
On entry, DS:DX contains the address of an ASCIIZ string with drive and | |||
directory path names. All directory levels other than the last one in the | |||
name must exist before using this function. Only one directory level at a | |||
time can be created with this function. The maximum length of the ASCIIZ | |||
string is 64 characters. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
Network Access Rights: Requires Create access rights. | |||
3AH -- | |||
REMOVE SUBDIRECTORY (RMDIR) | |||
PURPOSE | |||
Removes the specified directory. | |||
EXAMPLE | |||
MOV AX,SEG DName ;Directory name | |||
MOV DS,AX | |||
MOV DX,OFFSET DName | |||
MOV AH,3AH ;Function-Remove directory | |||
INT 21H ;Issue request to DOS | |||
JC Error | |||
DName DB "?? .. ??",0 ; ASCIIZ Name | |||
; example: "c:\dir",0 | |||
COMMENTS | |||
On entry, DS:DX contains the address of an ASCIIZ string with the drive and | |||
directory path names. The specified directory is removed from the structure. | |||
The current directory or a directory with files in it cannot be removed. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
Network Access Rights: Requires Create access rights. | |||
3BH -- | |||
CHANGE THE CURRENT DIRECTORY (CHDIR) | |||
PURPOSE | |||
Changes the current directory to the specified directory. | |||
EXAMPLE | |||
MOV AX,SEG DName ;Directory name | |||
MOV DS,AX | |||
MOV DX,OFFSET DName | |||
MOV AH,3BH ;Function -- Change directory | |||
INT 21H ;Issue request to DOS | |||
JC Error | |||
DName DB "?? .. ??",0 ; ASCIIZ Name | |||
; example: "c:\dir",0 | |||
COMMENTS | |||
On entry, DS:DX contains the address of an ASCIIZ string with drive and | |||
directory path names. The string is limited to 64 characters and cannot | |||
contain a network path. If any member of the directory path does not exist, | |||
the directory path is not changed. Otherwise, the current directory is set | |||
to the ASCIIZ string. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
3CH -- | |||
CREATE A FILE (CREAT) | |||
PURPOSE | |||
Creates a new file or shortens an old file to 0 length in preparation for | |||
writing. | |||
EXAMPLE | |||
MOV AX,SEG FName ;File name | |||
MOV DS,AX | |||
MOV DX,OFFSET FName | |||
MOV AH,3CH ;Function -- Create a File | |||
MOV CX,Attribute ; Attribute of the file | |||
; Allowed values | |||
; 0001H=Read only | |||
; 0002H=Hidden | |||
; 0004H=System | |||
; 0008H=Volume label | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV Handle,AX ; Save file handle for | |||
FName DB "?? .. ??",0 ; ASCIIZ Name | |||
; example: "c:\dir\file.ext",0 | |||
Handle DW ? ; File handle | |||
Attribute DW ? ; Attributes for directory entry | |||
COMMENTS | |||
If the file did not exist, the file is created in the appropriate directory | |||
and the file is given the read/write access code. The file is opened for | |||
read/write, the read/write pointer is set to the first byte of the file and | |||
the handle is returned in AX. Note that function call 43H (Change File Mode) | |||
can be used later to change the file's attribute. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
This function does not replace an existing volume label. You must delete the | |||
existing volume label before issuing this call. | |||
Network Access Rights: Requires Create access rights. | |||
3DH -- | |||
OPEN A FILE | |||
PURPOSE | |||
Opens the specified file. | |||
EXAMPLE | |||
MOV AX,SEG FName ; File name | |||
MOV DS,AX | |||
MOV DX,OFFSET FName | |||
MOV AH,3DH ; Function -- Open a File | |||
MOV AL,OpenMode | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV Handle,AX ; Save file handle for following operations | |||
FName DB "?? .. ??",0 ; ASCIIZ Name | |||
; example: "c:\dir\file.ext",0 | |||
Handle DW ? ; File Handle | |||
OpenMode DB ? ; Open mode | |||
COMMENTS | |||
The read/write pointer is set at the first byte of the file and the record | |||
size of the file is 1 byte. The read/write pointer can be changed with | |||
function call 42H. The returned file handle must be used for subsequent | |||
input and output to the file. The file's date and time can be obtained or | |||
set through call 57H, and its attribute can be obtained through call 43H. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
NOTES: | |||
1. This call opens any normal or hidden file whose name matches the name | |||
specified. | |||
2. Device names cannot end in a colon. | |||
3. When a file is closed, any sharing restrictions placed on it by the open | |||
are canceled. | |||
4. File sharing must be loaded, or the file must be a network file for the | |||
sharing modes to function. Refer to the SHARE command. | |||
5. The file read-only attribute can be set when creating the file using | |||
extended FCBs or specifying the appropriate attribute in CX and using the | |||
CHMOD interrupt 21H function call or the DOS 4.00 ATTRIB command. | |||
6. If the file is inherited by the subordinate process, all sharing and | |||
access restrictions are also inherited. | |||
7. If an open file handle is duplicated by either of the DUP function calls, | |||
all sharing and access restrictions are also duplicated. | |||
OPEN MODE | |||
The open mode is defined in AL and consists of four bit-oriented fields: | |||
INHERITANCE FLAG Specifies if the opened file is inherited by a | |||
subordinate process. | |||
SHARING MODE FIELD Defines which operations other processes can perform on | |||
the file. | |||
RESERVED FIELD | |||
ACCESS FIELD Defines which operations the current process can perform | |||
on the file. | |||
BIT FIELDS | |||
The bit fields are mapped as follows: | |||
<I> < S > <R> < A > | |||
Open Mode bits 7 6 5 4 3 2 1 0 | |||
I Inheritance flag | |||
If I = 0; File is inherited by subordinate processes. | |||
If I = 1; File is private to the current process. | |||
S Sharing Mode | |||
The file is opened as follows: | |||
S = 000 -- Compatibility mode | |||
S = 001 -- DenyRead/Write mode (exclusive) | |||
S = 010 -- DenyWrite mode | |||
S = 011 -- DenyRead mode | |||
S = 100 -- DenyNone mode | |||
Any other combinations are invalid. | |||
When opening a file, you must inform DOS 4.00 which operations any | |||
other processes, in sharing mode, can perform on the file. | |||
The default, compatibility mode, denies all other computers in a | |||
network access to the file. If other processes can continue to read | |||
the file while your process is operating on it, specify DenyWrite. | |||
DenyWrite prohibits writing by other processes, but allows reading. | |||
Similarly, you must specify which operations, or access modes, your | |||
process can perform. The default access mode, ReadWrite, causes the | |||
open request to fail if another process on the computer or any other | |||
computer on a network has the file opened with any sharing mode other | |||
than DenyNone. If you intend to read from the file only, your Open | |||
will succeed unless all other processes have specified DenyNone or | |||
DenyWrite. File sharing requires cooperation of both sharing | |||
processes. | |||
R Reserved (set this bit field to 0). | |||
A Access | |||
The file access is assigned as follows: | |||
If A = 000; Read access | |||
If A = 001; Write access | |||
If A = 010; Read/Write access | |||
Any other combinations are invalid. | |||
Network Access Rights: If the Access field (A) of the Open mode field (AL) | |||
is equal to: | |||
000 Requires Read access rights | |||
001 Requires Write access rights | |||
010 Requires Read/Write access rights | |||
COMPATIBILITY MODE | |||
A file is considered to be in compatibility mode if the file is opened by: | |||
Any of the CREATE function calls | |||
An FCB function call | |||
A handle function call with compatibility mode specified. | |||
A file can be opened any number of times in compatibility mode by a single | |||
process, provided that the file is not currently open under one of the other | |||
four sharing modes. If the file is marked read-only, and is open in | |||
DenyWrite sharing mode with Read Access, the file may be opened in | |||
Compatibility Mode with Read Access. If the file was successfully opened in | |||
one of the other sharing modes and an attempt is made to open the file again | |||
in Compatibility Mode, an interrupt 24H is generated to signal this error. | |||
The base interrupt 24H error indicates DRIVE NOT READY, and the extended | |||
error indicates a SHARING VIOLATION. | |||
SHARING MODES | |||
The sharing modes for a file opened in compatibility mode are changed by DOS | |||
4.00 depending on the read-only attribute of the file. This allows sharing | |||
of read-only files. | |||
+---------------------------------------------------+ | |||
| READ-ONLY | | |||
| FILE OPENED BY ACCESS SHARING MODE | | |||
+---------------------------------------------------+ | |||
| FCB Read-Only DenyWrite | | |||
+---------------------------------------------------+ | |||
| Handle Read Read-Only DenyWrite | | |||
+---------------------------------------------------+ | |||
| Handle Write Error ----- | | |||
+---------------------------------------------------+ | |||
| Handle Error ----- | | |||
| Read/Write | | |||
+---------------------------------------------------+ | |||
+---------------------------------------------------+ | |||
| NOT READ-ONLY | | |||
| FILE OPENED BY ACCESS SHARING MODE | | |||
+---------------------------------------------------+ | |||
| FCB Read/Write Compatibility | | |||
+---------------------------------------------------+ | |||
| Handle Read Read Compatibility | | |||
+---------------------------------------------------+ | |||
| Handle Write Write Compatibility | | |||
+---------------------------------------------------+ | |||
| Handle Read/Write Compatibility | | |||
| Read/Write | | |||
+---------------------------------------------------+ | |||
DENYREAD/WRITE MODE (EXCLUSIVE) | |||
If a file is successfully opened in DenyRead/Write mode, access to the file | |||
is exclusive. A file currently open in this mode cannot be opened again in | |||
any sharing mode by any process (including the current process) until the | |||
file is closed. | |||
DENYWRITE MODE | |||
A file successfully opened in DenyWrite sharing mode, prevents any other | |||
write access opens to the file (A = 001 or 010) until the file is closed. An | |||
attempt to open a file in DenyWrite mode is unsuccessful if the file is open | |||
with a write access. | |||
DENYREAD MODE | |||
A file successfully opened in DenyRead sharing mode, prevents any other read | |||
sharing access opens to the file (A = 000 or 010) until the file is closed. | |||
An attempt to open a file in DenyRead sharing mode is unsuccessful if the | |||
file is open in Compatibility mode or with a read access. | |||
DENYNONE MODE | |||
A file successfully opened in DenyNone mode, places no restrictions on the | |||
read/write accessibility of the file. An attempt to open a file in DenyNone | |||
mode is unsuccessful if the file is open in Compatibility mode. | |||
When accessing files that reside on a network disk, no local buffering is | |||
done when files are opened in any of the following sharing modes: | |||
DenyRead | |||
DenyNone. | |||
Therefore, in a network environment, DenyRead/Write sharing mode, | |||
Compatibility sharing mode, and DenyWrite mode opens are buffered locally. | |||
The following sharing matrix shows the results of opening, and subsequently | |||
attempting to reopen the same file using all combinations of access and | |||
sharing modes: | |||
Y :2nd,3rd,...open is allowed | |||
N :2nd,3rd,...open is denied | |||
DRW :DenyRead/Write Mode (Exclusive) | |||
DW :DenyWrite Mode | |||
DR :DenyRead Mode | |||
ALL :Read/Write Mode | |||
I :Read Only Access | |||
O :Write Only Access | |||
IO :Read/Write Access | |||
3EH -- | |||
CLOSE A FILE HANDLE | |||
PURPOSE | |||
Closes the specified file handle. | |||
EXAMPLE | |||
MOV AH,3EH ; Function Call -- | |||
; Close a Handle | |||
MOV BX,Handle | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
Handle DW ? ; File Handle (from Open / Create) | |||
COMMENTS | |||
On entry, BX contains the file handle that was returned by Open or Create. | |||
On return, the file is closed, the directory is updated, and all internal | |||
buffers for that file are flushed. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
3FH -- | |||
READ FROM A FILE OR DEVICE | |||
PURPOSE | |||
Transfers the specified number of bytes from a file into a buffer location. | |||
EXAMPLE | |||
MOV AX,SEG Buffer ; Address data buffer | |||
MOV DS,AX | |||
MOV DX,OFFSET Buffer | |||
MOV AH,3FH ; Function -- Read from a file | |||
MOV BX,Handle | |||
MOV CX,BufSize ; Buffer size | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
CMP AX,0 ; At End Of File? | |||
JE EOF ; Yes! | |||
MOV SizeRead,AX ; Save Amount Read | |||
N EQU 512 ; Typical buffer size | |||
Handle DW ? ; File Handle (from Open /Create) | |||
BufSize DW N ; Buffer Size, N is | |||
Buffer DB N DUP(?) ; Data Buffer | |||
SizeRead DW ? ; Amount of Data in Buffer | |||
COMMENTS | |||
On entry, BX contains the file handle. CX contains the number of bytes to | |||
read. DS:DX contains the buffer address. On return, AX contains the number | |||
of bytes read. | |||
This function call attempts to transfer (CX) bytes from a file into a buffer | |||
location. It is not guaranteed that all bytes will be read. For example, | |||
when DOS 4.00 reads from the keyboard, at most one line of text is | |||
transferred. If this read is performed from the standard input device, the | |||
input can be redirected. If the value in AX is 0, then the program has tried | |||
to read from the end of file. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
Network Access Rights: Requires Read access rights. | |||
40H -- | |||
WRITE TO A FILE OR DEVICE | |||
PURPOSE | |||
Transfers the specified number of bytes from a buffer into a specified file. | |||
EXAMPLE | |||
MOV AX,SEG Buffer ;Data Buffer | |||
MOV DS,AX | |||
MOV DX,OFFSET Buffer | |||
MOV CX,BufSize | |||
MOV AH,40H ;Function-Write to a File | |||
MOV BX,Handle | |||
MOV DX,OFFSET Buffer | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
CMP AX,CX ; Disk Full? | |||
JB FullDisk ; Yes! | |||
N EQU 512 ; Typical buffer size | |||
Handle DW ? ; File Handle (from Open / Create) | |||
BufSize DW N ; Buffer Size | |||
Buffer DB N DUP(?) ; Data Buffer | |||
COMMENTS | |||
On entry, BX contains the file handle. CX contains the number of bytes to | |||
write. DS:DX contains the address of the data to write. | |||
This function call attempts to transfer (CX) bytes from a buffer into a file. | |||
AX returns the number of bytes actually written. If the carry flag is not | |||
set and this value is not the same as the number requested (in CX), it should | |||
be considered an error. Although no error code is returned, your program can | |||
compare these values. Normally, the reason for the error is a full disk. If | |||
this write is performed to the standard output device, the output can be | |||
redirected. | |||
To truncate a file at the current position of the file pointer, set the | |||
number of bytes (CX) to 0 before issuing the interrupt 21H. The file pointer | |||
can be moved to the desired position by reading, writing, and performing | |||
function call 42H, (Move File Read/Write Pointer.) | |||
If the file is read-only, the write to the file or device is not performed. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
Network Access Rights: Requires Write access rights. | |||
41H -- | |||
DELETE A FILE FROM A SPECIFIED DIRECTORY (UNLINK) | |||
PURPOSE | |||
Removes a directory entry associated with a filename. | |||
EXAMPLE | |||
MOV AX,SEG FName ; File Name | |||
MOV DS,AX | |||
MOV DX,OFFSET FName | |||
MOV AH,41H ; Function-Delete a File | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
FName DB "?? .. ??",0 ; ASCIIZ Name | |||
; example: "c:\dir\File.ext",0 | |||
COMMENTS | |||
Global filename characters are not allowed in any part of the ASCIIZ string. | |||
Read-only files cannot be deleted by this call. To delete a read-only file, | |||
you can first use call 43H to change the file's read-only attribute to 0, | |||
then delete the file. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
Network Access Rights: Requires Create access rights. | |||
42H -- | |||
MOVE FILE READ WRITE POINTER (LSEEK) | |||
PURPOSE | |||
Moves the read/write pointer according to the method specified. | |||
EXAMPLE | |||
MOV AH,42H ; Function Call -- | |||
; Move Read/Write Pointer | |||
MOV AL,Method ; Method of Positioning: | |||
; 0 = From Beginning of File | |||
; (BOF) | |||
; 1 = From Current Position | |||
; 2 = From End of File (EOF) | |||
MOV BX,Handle ; Select File | |||
MOV DX,WORD PTR Position+0 ; New Position = Position + METHOD | |||
MOV CX,WORD PTR Position+2 | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV WORD PTR Position+0,AX ; Set new File Position | |||
MOV WORD PTR Position+2,DX | |||
Handle DW ? ; File Handle (from Open / | |||
; Create) | |||
Position DD ? ; File Offset (may be | |||
; negative) | |||
Method DB ? | |||
COMMENTS | |||
On entry, AL contains a method value. BX contains the file handle. CX:DX | |||
contains the desired offset in bytes with CX containing the most significant | |||
part. On return, DX:AX contains the new location of the pointer with DX | |||
containing the most significant part if the carry flag is not set. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
This function call moves the read/write pointer according to the following | |||
methods: | |||
+---------+-----------------------------------------------------------------+ | |||
| AL | DESCRIPTION | | |||
+---------+-----------------------------------------------------------------+ | |||
| 0 | The pointer is moved CX:DX bytes (offset) from the beginning of | | |||
| | the file. | | |||
+---------+-----------------------------------------------------------------+ | |||
| 1 | The pointer is moved to the current location plus offset. | | |||
+---------+-----------------------------------------------------------------+ | |||
| 2 | The pointer is moved to the end-of-file plus offset. This | | |||
| | method can be used to determine file's size. | | |||
+---------+-----------------------------------------------------------------+ | |||
NOTE: If an LSEEK operation is performed on a file that resides on a network | |||
disk that is open in either DenyRead or DenyNone sharing mode, the | |||
read/write pointer information is adjusted on the computer where the | |||
file actually exists. If the file is opened in any other sharing | |||
mode, the read/write pointer information is kept on the remote | |||
computer. | |||
43H -- | |||
CHANGE FILE MODE (CHMOD) | |||
PURPOSE | |||
Changes the file mode of the specified file. | |||
EXAMPLE | |||
; To Get Attributes | |||
MOV AX,SEG FName ;File Name | |||
MOV DS,AX | |||
MOV DX,OFFSET FName ;DS:DX points to ASCIIZ path name | |||
MOV AL,0 ;Indicate get | |||
MOV AH,43H ;Function-Change File Mode | |||
INT 21H ;Issue request to DOS | |||
JC Error ;Error code in AX | |||
MOV Attribute,CX ;Save Attribute | |||
; To Set Attributes | |||
MOV AX,SEG FName ;File Name | |||
MOV DS,AX | |||
MOV DX,OFFSET FName ;DS:DX points to ASCIIZ path name | |||
MOV AL,1 ;Indicate set | |||
MOV AH,43H ;Function-Change File Mode | |||
MOV CX,Attribute ;Set Attribute | |||
INT 21H ;Issue request to DOS | |||
JC Error ;Error code in AX | |||
Fname DB 64 Dup (0) ;ASCIIZ Name | |||
; example: "c:\dir\File.ext",0 | |||
Attribute DW ? ;File Attribute | |||
; example: 0001H to set Read-Only | |||
COMMENTS | |||
On entry, AL contains a function code, and DS:DX contains the address of an | |||
ASCIIZ string with the drive, path, and filename. | |||
If AL contains 01H, the file's attribute is set to the attribute in CX. See | |||
"The Disk Directory" on page 2-3 for the attribute byte description. If AL | |||
is 00H the file's current attribute is returned in CX. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
NOTE: Only the Archive (20H), Read-Only (01H), System (04H) and Hidden (02H) | |||
bits can be changed. All other bits of CX must be 0, otherwise, an | |||
error may be indicated. | |||
Network Access Rights: To change the archive bit (AL=20H), no access rights | |||
are required. To change any other bit, Create access rights are required. | |||
44H -- | |||
I/O CONTROL FOR DEVICES | |||
PURPOSE | |||
Sets or gets device information associated with open device handles, or sends | |||
control strings to the device handle or receives control strings from the | |||
device handle. | |||
See Appendix C for full details on this function call. | |||
45H -- | |||
DUPLICATE A FILE HANDLE (DUP) | |||
PURPOSE | |||
Returns a new file handle for an open file that refers to the same file at | |||
the same position. | |||
EXAMPLE | |||
MOV AH,45H ; Function Call -- | |||
; Duplicate a Handle | |||
MOV BX,Handle ; Select File | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV NewHandle,AX ; Save New Handle | |||
Handle DW ? ; File Handle (from Open / Create) | |||
NewHandle DW ? ; File Handle that duplicates Handle | |||
COMMENTS | |||
On entry, BX contains the file handle. On return, AX contains the returned | |||
file handle. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
NOTE: If you move the read/write pointer of either handle by a read, write, | |||
or LSEEK function call, the pointer for the other handle is also | |||
changed. | |||
46H -- | |||
FORCE A DUPLICATE OF A HANDLE (FORCDUP) | |||
PURPOSE | |||
Forces the handle in CX to refer to the same file at the same position as the | |||
handle in BX. | |||
EXAMPLE | |||
MOV AH,46H ; Function Call -- | |||
; Force Duplicate a Handle | |||
MOV BX,Handle ; Select file | |||
MOV CX,NewHandle ; Select new definition of File | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
Handle DW ? ; File Handle (from Open/Create) | |||
NewHandle DW ? ; File Handle that duplicates Handle | |||
COMMENTS | |||
On entry, BX contains the file handle. CX contains a second file handle. On | |||
return, the CX file handle refers to the same file at the same position as | |||
the BX file handle. If the CX file handle was an open file, it is closed | |||
first. If you move the read/write pointer of either handle, the pointer for | |||
the other handle is also changed. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
47H -- | |||
GET CURRENT DIRECTORY | |||
PURPOSE | |||
Places the full path name (starting from the root directory) of the current | |||
directory for the specified drive in the area pointed to by DS:SI. | |||
EXAMPLE | |||
MOV AX,SEG DName ; Directory Name Buffer | |||
MOV DS,AX | |||
MOV SI,OFFSET DName ; OS:SI points to buffer | |||
MOV DL,Drive ; Select Drive | |||
MOV AH,47H ; Function-Get Current Dir | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
Drive DB ? ; Drive (0=current, 1=A:, 2=b:, ...) | |||
DName DB 64 DUP(?) ; ASCIIZ Directory Name Returned | |||
; example: "dir1\dir2",0 | |||
COMMENTS | |||
The drive letter is not part of the returned string. The string does not | |||
begin with a backslash and is terminated by a byte containing 00H. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
48H -- | |||
ALLOCATE MEMORY | |||
Allocates the requested number of paragraphs of memory. | |||
EXAMPLE | |||
MOV AH,48H ; Function Call -- | |||
; Allocate Memory | |||
MOV BX,Paragraphs ; Paragraphs Desired | |||
INT 21H ; Issue request to DOS | |||
JNC Done | |||
MOV AH,48H ; Function Call -- | |||
; Allocate memory | |||
; BX set to largest available memory | |||
INT 21H ; Issue request to DOS | |||
Done: | |||
MOV BlockSeg,AX ; Save BlockSeg of memory | |||
MOV Paragraphs,BX | |||
Paragraphs DW ? ; Size requested in paragraphs | |||
; (Bytes allocated is 16 * Paragraphs) | |||
BlockSeg DW ? ; BlockSeg address of allocated memory | |||
COMMENTS | |||
On entry, BX contains the number of paragraphs requested. On return, AX:0 | |||
points to the allocated memory block. If the allocation fails, BX returns | |||
the size of the largest block of memory available in paragraphs. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
49H -- | |||
FREE ALLOCATED MEMORY | |||
PURPOSE | |||
Frees the specified allocated memory. | |||
EXAMPLE | |||
MOV AH,49H ; Function Call -- Free Memory | |||
MOV ES,BlockSeg ; Set address to free | |||
INT 21H ; Issue request to DOS | |||
JC Error | |||
BlockSeg DW ? ; BlockSeg address of allocated memory | |||
COMMENTS | |||
On entry, ES contains the segment of the block to be returned to the system | |||
pool. On return, the block of memory is returned to the system pool. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
4AH -- | |||
MODIFY ALLOCATED MEMORY BLOCKS (SETBLOCK) | |||
PURPOSE | |||
Modifies allocated memory blocks to contain the new specified block size. | |||
EXAMPLE | |||
MOV AH,4AH ; Function Call -- | |||
; Modify Allocated Memory; allocate memory | |||
MOV ES,BlockSeg ; Set address to free | |||
MOV BX,BlockSize ; New size (may be larger or smaller) | |||
INT 21H ; Issue request to DOS | |||
JNC Done | |||
MOV AH,4AH ; Function Call -- | |||
; Allocate memory | |||
; BX set to largest available Size | |||
INT 21H ; Issue request to DOS | |||
Done: | |||
MOV Size,BX | |||
BlockSeg DW ? ; Segment address of allocated memory | |||
BlockSize DW ? ; Size requested in paragraphs | |||
; (Bytes allocated is 16 * Size) | |||
COMMENTS | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
NOTE: This call is often used to set the size of a program before using | |||
function call 31H (Terminate Process and Remain Resident). Use the | |||
program segment prefix. This value can be obtained using function | |||
call 62H (Get Program Segment Prefix Address). Another use is to | |||
release memory to prepare for using function call 4BH (Load or Execute | |||
a Program). | |||
4BH -- | |||
LOAD OR EXECUTE A PROGRAM (EXEC) | |||
PURPOSE | |||
Allows a program to load another program into memory and may choose to begin | |||
execution of it. | |||
EXAMPLE | |||
; To Execute a Program | |||
MOV AH,4BH ; Function Call -- Execute a Program | |||
MOV AL,0 ; Indicate execute program | |||
MOV CX,SEG Parms ; Program parameters | |||
MOV ES,CX | |||
MOV BX,OFFSET Parms : ES:BX points to parameter block | |||
MOV CX,SEG PName ; Program name | |||
MOV DS,CX | |||
MOV DX,OFFSET PName ; DS:DX points to program name | |||
MOV WORD PTR StackSave+0,SP ; Save stack pointer | |||
MOV WORD PTR StackSave+2,SS | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
; Note: All Registers (except CS:IP) Destroyed | |||
; Program Runs here | |||
CLI ; Protect from stack usage | |||
MOV SS,WORD PTR StackSave+2 ; Restore stack pointer | |||
MOV SP,WORD PTR StackSave+0 | |||
STI ; Enable interrupts | |||
MOV AH,4DH ; Function Call -- Get Return Code | |||
INT 21H ; Issue request to DOS | |||
MOV RetCode,AX ; Save return code | |||
; To Load an Overlay | |||
MOV AH,4BH ; Function Call -- Execute a Program | |||
MOV AL,3 ; Indicate load overlay | |||
MOV CX,SEG OParms ; Overlay parameters | |||
MOV ES,CX | |||
MOV BX,OFFSET OParms ; ES:BX points to parameter block | |||
MOV CX,SEG PName ; Overlay name | |||
MOV DS,CX | |||
MOV DX,OFFSET PName ; DS:DX points to overlay filename | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
PName DB 64 Dup (0) ; ASCIIZ Name | |||
; example: "c:\dir\File.ext",0 | |||
Parms LABEL WORD ; Program parameters | |||
Env@ DW ? ; Environment segment address | |||
; Value of 0000H indicates copy EXEC'ers | |||
; Environment | |||
Cmd@ DD ? ; Command line address | |||
FCB1@ DD ? ; FCB Image to set to New PSP+5CH | |||
FCB2@ DD ? ; FCB Image to set to New PSP+6CH | |||
StackSave DD ? ; Stack pointer save area | |||
RetCode DW ? ; Program return code | |||
; (see function code 4DH for more informatio | |||
OParms LABEL WORD ; Overlay parameters | |||
Load@ DW ? ; Overlay load segment address | |||
RelocFactor DW ? ; Relocation factor to apply (for .EXE files | |||
COMMENTS | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. Refer to "Responding to Errors" on page B-5 and "Extended Error | |||
Codes" on page B-5 for more information on the codes returned from function | |||
call 59H. | |||
The following function values are allowed in AL: | |||
+---------------------------------------------------------------------------+ | |||
| FUNCTION | | |||
| VALUE DESCRIPTION | | |||
+---------------------------------------------------------------------------+ | |||
| 00H Load and execute the program. A program segment prefix is | | |||
| established for the program; terminate and Ctrl-Break addresses | | |||
| are set to the instruction after the EXEC system call. | | |||
| | | |||
| NOTE: When control is returned, all registers are changed, | | |||
| including the stack. You must restore SS, SP, and any | | |||
| other required registers before proceeding. | | |||
+---------------------------------------------------------------------------+ | |||
| 03H Load, do not create the program segment prefix, and do not | | |||
| begin execution. This is useful in loading program overlays. | | |||
+---------------------------------------------------------------------------+ | |||
All open files of a process are duplicated in the newly created process after | |||
an EXEC, unless the file was opened with the inheritance bit set to 1. This | |||
means that the parent process has control over the meanings of standard | |||
input, output, auxiliary, and printer devices. The parent could, for | |||
example, write a series of records to a file, open the file as standard | |||
input, open a listing file as standard output, and then execute a sort | |||
program that takes its input from standard input and writes to standard | |||
output. | |||
Also inherited (or copied from the parent) is an "environment." This is a | |||
block of text strings (less than 32KB total) that conveys various | |||
configuration parameters. The following is the format of the environment | |||
(always on a paragraph boundary): | |||
+---------------------------------------------------------------------------+ | |||
| Byte ASCIIZ string 1 | | |||
+---------------------------------------------------------------------------+ | |||
| Byte ASCIIZ string 2 | | |||
+---------------------------------------------------------------------------+ | |||
| ... | | |||
+---------------------------------------------------------------------------+ | |||
| Byte ASCIIZ string n | | |||
+---------------------------------------------------------------------------+ | |||
| Byte of 0 | | |||
+---------------------------------------------------------------------------+ | |||
Typically the environment strings have the form: | |||
parameter=value | |||
Following the byte of 0 in the environment is a WORD that indicates the | |||
number of other strings following. Following this is a copy of the DS:DX | |||
filename passed to the child process. For example, the string VERIFY=ON | |||
could be passed. A 0 value of the environment address causes the newly | |||
created process to inherit the original environment unchanged. The segment | |||
address of the environment is placed at offset 2CH of the program segment | |||
prefix for the program being invoked. | |||
Errors codes are returned in AX. Refer to "Responding to Errors" on page B-5 | |||
and "Extended Error Codes" on page B-5 for more information on the codes | |||
returned. | |||
NOTE: When your program received control, all available memory was allocated | |||
to it. You must free some memory (see call 4AH) before EXEC can load | |||
the program you are invoking. Normally, you would shrink down to the | |||
minimum amount of memory you need, and free the rest. | |||
4CH -- | |||
TERMINATE A PROCESS (EXIT) | |||
PURPOSE | |||
Terminates the current process and transfers control to the invoking process. | |||
EXAMPLE | |||
MOV AH,4CH ; Function Call -- Terminate a Process | |||
MOV AL,ErrorCode ; Set ERRORLEVEL | |||
INT 21H ; Issue request to DOS | |||
INT 20H ; Be safe if running on PC/DOS 1.1 | |||
ErrorCode DB ? ; Error Code (sets ERRORLEVEL if EXEC'ed | |||
; by COMMAND.COM) | |||
COMMENTS | |||
In addition, a return code can be sent. The return code can be interrogated | |||
by the batch subcommands IF and ERRORLEVEL and by the wait function call 4DH. | |||
All files opened by this process are closed. | |||
4DH -- | |||
GET RETURN CODE OF A SUBPROCESS (WAIT) | |||
PURPOSE | |||
Gets the return code specified by another process either through function | |||
call 4CH or function call 31H. It returns the Exit code only once. | |||
EXAMPLE | |||
MOV AH,4DH ; Function Call -- Get Return Code | |||
INT 21H ; Issue request to DOS | |||
MOV RetCode,AX ; Save return code | |||
RetCode LABEL WORD ; Program return code | |||
ExitCode DB ? ; ERRORLEVEL value | |||
ExitType DB ? ; Method used to exit: | |||
; 00H -- for normal termination | |||
; 01H -- for termination by Ctrl-Break | |||
; 02H -- for termination as a result | |||
; of a critical device error | |||
; 03H -- for termination by call 31H | |||
COMMENTS | |||
The low byte of the exit code contains the information sent by the exiting | |||
routine. | |||
4EH -- | |||
FIND FIRST MATCHING FILE (FIND FIRST) | |||
PURPOSE | |||
Finds the first filename that matches the specified file specification. | |||
EXAMPLE | |||
MOV AH,1AH ; Function Call -- Set DTA Address | |||
MOV CX,SEG DTA ; Address buffer for found file | |||
MOV DS,CX | |||
MOV DX,OFFSET DTA | |||
INT 21H ; Issue request to DOS | |||
MOV AH,4EH ; Function Call -- ASCIIZ Find First | |||
MOV CX,SEG FName ; Directory or filename | |||
MOV DS,CX | |||
MOV DX,OFFSET FName ; DS:DX points to ASCII filename | |||
MOV CX,Attribute ; Set Match Attribute | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
DTA LABEL BYTE ; Find return information | |||
DB 21 DUP(0) ; Reserved for DOS 4.00 to continu | |||
FileAttr DB ? ; Matched files attribute low byte | |||
FileTime DW ? ; File time | |||
FileDate DW ? ; File date | |||
FileSize DD ? ; File size | |||
FileNameExt DB "????????.???",0 ; Filename and extension | |||
FName DB 64 DUP (0) ; ASCIIZ Name | |||
; example: "c:\dir\*.*",0 | |||
Attribute DW ? ; Select files attribute | |||
; Combination of following: | |||
; 0002H=Hidden | |||
; 0004H=System | |||
; 0008H=Volume label | |||
; 0010H=Directory | |||
NOTES: | |||
If an extended FCB is used, the following search pattern is used: | |||
1. If the attribute is 0, only normal file entries are found. Entries for | |||
volume label, sub-directories, hidden and system files are not returned. | |||
2. If the attribute field is set for hidden or system files, or directory | |||
entries, it is to be considered as an inclusive search. All normal file | |||
entries plus all entries matching the specified attributes are returned. | |||
To look at all directory entries except the volume label, the attribute | |||
byte may be set to hidden + system + directory (all 3 bits on). | |||
3. If the attribute field is set for the volume label, it is considered an | |||
exclusive search, and only the volume label entry is returned. | |||
COMMENTS | |||
The filename in DS:DX can contain global filename characters. The ASCIIZ | |||
string cannot contain a network path. See function call 11H (Search for | |||
First Entry) for a description of how the attribute bits are used for | |||
searches. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. Refer to "Responding to Errors" on page B-5 and "Extended Error | |||
Codes" on page B-5 for more information on the codes returned from function | |||
call 59H. | |||
NOTE: The name and extension of file found is returned as an ASCIIZ string. | |||
All blanks are removed from the name and extension, and, if an | |||
extension is present, it is preceded by a period. | |||
4FH -- | |||
FIND NEXT MATCHING FILE (FIND NEXT) | |||
PURPOSE | |||
Finds the next directory entry matching the name that was specified on the | |||
previous Find First or Find Next function call. | |||
EXAMPLE | |||
MOV AH,1AH ; Function Call -- Set DTA Address | |||
MOV CX,SEG DTA ; Address buffer for found file | |||
MOV DS,CX | |||
MOV DX,OFFSET DTA | |||
INT 21H ; Issue request to DOS | |||
MOV AH,4FH ; Function Call -- Find next | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
DTA LABEL BYTE " ; Find Return Information | |||
DB 21 DUP(0) " ; Reserved for DOS to Continue Find | |||
" ; Set by Find First or Previous Fin | |||
FileAttr DB ? " ; Matched Files Attribute Low Byte | |||
FileTime DW ? " ; File Time | |||
FileDate DW ? " ; File Date | |||
FileSize DD ? " ; File Size | |||
FileNameExt DB "????????.???",0 ; File Name and Extension | |||
COMMENTS | |||
If a matching file is found, the DTA is set as described in call 4EH (Find | |||
First Matching File (FIND FIRST)). If no more matching files are found, an | |||
error code is returned. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. | |||
54H -- | |||
GET VERIFY SETTING | |||
PURPOSE | |||
Returns the value of the verify flag. | |||
EXAMPLE | |||
MOV AH,54H ; Function Call -- Get VERIFY Setting | |||
INT 21H ; Issue request to DOS | |||
MOV VERIFY,AL ; Save VERIFY State | |||
VERIFY DB ? ; VERIFY State: | |||
; 0 = OFF | |||
; 1 = ON | |||
COMMENTS | |||
On return, AL returns 00H if verify is OFF, 01H if verify is ON. Note that | |||
the verify switch can be set through call 2EH (Set/Reset Verify Switch). | |||
56H -- | |||
RENAME A FILE | |||
PURPOSE | |||
Renames the specified file. | |||
EXAMPLE | |||
MOV AH,56H ; Function Call -- ASCIIZ Rename File | |||
MOV CX,SEG FName ; File Name | |||
MOV DS,CX | |||
MOV DX,OFFSET FName ; DS:DX points to original name | |||
MOV CX,SEG NewName ; New File Name | |||
MOV ES,CX | |||
MOV DI,OFFSET NewName ; ES:DI points to rename | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
FName DB 64 DUP (0) ; ASCIIZ Name | |||
; example: "c:\dir\abc.lst",0 | |||
NewName DB 64 DUP (0) ; ASCIIZ Name | |||
; example: "\dir\xyz.lst",0 | |||
COMMENTS | |||
If a drive is used in the NewName string, it must be the same as the drive | |||
specified or implied in the Name string. The directory paths need not be the | |||
same, allowing a file to be moved to another directory and renamed in the | |||
process. Directory names can be changed but not moved. Global filename | |||
characters are not allowed in the filename. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. Refer to "Responding to Errors" on page B-5 and "Extended Error | |||
Codes" on page B-5 for more information on the codes returned from function | |||
call 59H. | |||
Network Access Rights: Requires Create access rights. | |||
57H -- | |||
GET/SET FILE'S DATE AND TIME | |||
PURPOSE | |||
Gets or sets a file's date and time. | |||
EXAMPLE | |||
; To Get a File's Date and Time | |||
MOV AH,57H ; Function Call -- Get/Set Date and Time | |||
MOV AL,0 ; Indicate get | |||
MOV BX,Handle ; Select file | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV FileTime,CX ; Save Time | |||
MOV FileDate,DX ; Save Date | |||
; To Set a File's Date and Time | |||
MOV AH,57H ; Function Call -- Get/Set Date and Time | |||
MOV AL,1 ; Indicate Set | |||
MOV BX,Handle ; Select file+ | |||
MOV CX,FileTime ; Set Time | |||
MOV DX,FileDate ; Set Date | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
Handle DW ? ; File Handle (from Open / Create) | |||
FileTime DW ? ; File Time | |||
FileDate DW ? ; File Date | |||
COMMENTS | |||
The date and time formats are the same as those for the directory entry | |||
described in Chapter 5 of this book. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. Refer to "Responding to Errors" on page B-5 and "Extended Error | |||
Codes" on page B-5 for more information on the codes returned from function | |||
call 59H. | |||
59H -- | |||
GET EXTENDED ERROR | |||
PURPOSE | |||
Returns additional error information, such as the error class, location, and | |||
recommended action. | |||
EXAMPLE | |||
PUSH DX ; Save Registers | |||
PUSH SI | |||
PUSH DI | |||
PUSH ES | |||
PUSH DS | |||
MOV AH,59H ; Function Call -- Get Extended Error | |||
MOV BX,0 ; Version 0 information | |||
INT 21H ; Issue request to DOS | |||
POP DS ; Restore registers | |||
POP ES | |||
POP DI | |||
POP SI | |||
POP DX | |||
MOV ExtError,AX ; Save error code | |||
MOV ErrorClass,BH ; Save error class | |||
MOV ErrorAction,BL ; Save error action | |||
MOV ErrorLocation,CH; Save error location | |||
ExtError DW ? ; DOS extended error | |||
ErrorClass DB ? ; Class of error | |||
ErrorAction DB ? ; Suggested action | |||
ErrorLocation DB ? ; System area effected | |||
COMMENTS | |||
This function call returns the error class, location, and recommended action, | |||
in addition to the return code. Use this function call from: | |||
Interrupt 24H error handlers | |||
Interrupt 21H function calls that return an error in the carry bit | |||
FCB function calls that return FFH. | |||
On return, the registers contents of DX, SI, DI, ES, CL, and DS are | |||
destroyed. | |||
ERROR RETURN IN CARRY BIT | |||
For function calls that indicate an error by setting the carry flag, the | |||
correct method for performing function call 59H is: | |||
Load registers. | |||
Issue interrupt 21H. | |||
Continue operation, if carry not set. | |||
Disregard the error code and issue function call 59H to obtain additional | |||
information. | |||
Use the value in BL to determine the suggested action to take. | |||
ERROR STATUS IN AL | |||
For function calls that indicate an error by setting AL to FFH, the correct | |||
method for performing function call 59H is: | |||
Load registers. | |||
Issue interrupt 21H. | |||
Continue operation, if error is not reported in AL. | |||
Disregard the error code and issue function call 59H to obtain additional | |||
information. | |||
Use the value in BL to determine the suggested action to take. | |||
5AH -- | |||
CREATE UNIQUE FILE | |||
PURPOSE | |||
Generates a unique filename, and creates that file in the specified | |||
directory. | |||
EXAMPLE | |||
MOV AH,5AH ; Function Call -- Create a | |||
; Unique File | |||
MOV CX,SEG DirName ; Directory name | |||
MOV DS,CX | |||
MOV DX,OFFSET DirName | |||
MOV CX,Attribute ; File attribute | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV Handle,AX ; Save file handle for following | |||
; Operations | |||
DirName DB "?? .. ??\",0 ; ASCIIZ name | |||
DB "????????.???" | |||
; example in : "c:\dir\",0 | |||
; example out: "c:\dir\file",0 | |||
Handle DW ? ; File handle | |||
Attribute DW ? ; Select file's attribute | |||
COMMENTS | |||
On entry, AH contains 5AH. If no error has occurred, the file is opened in | |||
compatibility mode with Read/Write access. The read/write pointer is set at | |||
the first byte of the file and AX contains the file handle and the filename | |||
is appended to the path specified in DS:DX. | |||
This function call generates a unique name and attempts to create a new file | |||
in the specified directory. If the file already exists in the directory, | |||
then another unique name is generated and the process is repeated. Programs | |||
that need temporary files should use this function call to generate unique | |||
filenames. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. Refer to "Responding to Errors" on page B-5 and "Extended Error | |||
Codes" on page B-5 for more information on the codes returned from function | |||
call 59H. | |||
NOTE: The file created using this function call is not automatically deleted | |||
at program termination. | |||
Network Access Rights: Requires Create access rights. | |||
5BH -- | |||
CREATE NEW FILE | |||
PURPOSE | |||
Creates a new file. | |||
EXAMPLE | |||
MOV AH,5BH ; Function Call -- Create a New File | |||
MOV CX,SEG FName ; File Name | |||
MOV DS,CX | |||
MOV DX,OFFSET FName | |||
MOV CX,Attribute | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV Handle,AX ; Save File Handle for following operations | |||
FName DB 64 DUP (0) ; ASCIIZ Name | |||
; example: "c:\dir\file",0 | |||
Handle DW ? ; File Handle | |||
Attribute DW ? ; Select File's Attribute | |||
COMMENTS | |||
This function call is the same as function call 3CH (Create), except it will | |||
fail if the filename already exists. The file is created in compatibility | |||
mode for reading and writing and the read/write pointer is set at the first | |||
byte of the file. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. Refer to "Responding to Errors" on page B-5 and "Extended Error | |||
Codes" on page B-5 for more information on the codes returned from function | |||
call 59H. | |||
Network Access Rights: Requires Create access rights. | |||
5CH -- | |||
LOCK/UNLOCK FILE ACCESS | |||
PURPOSE | |||
Locks or unlocks a single range of bytes in an opened file. This function | |||
call provides database services that are useful in maintaining database | |||
integrity in a network environment. | |||
EXAMPLE | |||
; To Lock a Single Range | |||
MOV AH,5CH ; Function Call -- | |||
; Access Lock/Unlock File | |||
MOV AL,0 ; Indicate lock | |||
MOV BX,Handle ; Select file | |||
MOV DX,WORD PTR Position+0 ; Set position | |||
MOV CX,WORD PTR Position+2 | |||
MOV DI,WORD PTR Llength+0 ; Set length | |||
MOV SI,WORD PTR Llength+2 | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
; To Unlock a Single Range | |||
MOV AH,5CH ; Function Call -- | |||
; Lock/Unlock File Access | |||
MOV AL,1 ; Indicate unlock | |||
MOV BX,Handle ; Select file | |||
MOV DX,WORD PTR Position+0 ; Set position | |||
MOV CX,WORD PTR Position+2 | |||
MOV DI,WORD PTR Llength+0 ; Set length | |||
MOV SI,WORD PTR Llength+2 | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
Handle DW ? ; File Handle | |||
Position DD ? ; Start of Range | |||
Llength DD ? ; Length of Range | |||
COMMENTS | |||
The Lock/Unlock function calls should only be used when a file is opened | |||
using the DenyRead or DenyNone sharing modes. These modes do no local | |||
buffering of data when accessing files on a network disk. | |||
AL = 00H LOCK | |||
Provides a simple mechanism for excluding other processes' read/write access | |||
to regions of the file. If another process attempts to read or write in such | |||
a region, its system call is retried the number of times specified with the | |||
system retry count set by IOCTL. If, after those retries, no success occurs, | |||
a general failure error is generated, signaling the condition. The number of | |||
retries, as well as the length of time between retries, can be changed using | |||
function call 440BH (IOCTL Change Sharing Retry Count). | |||
The recommended action is to issue function call 59H (Get Extended Error) to | |||
get the error code, in addition to the error class, location, and recommended | |||
action. The locked regions can be anywhere in the logical file. Locking | |||
beyond end-of-file is not an error. It is expected that the time in which | |||
regions are locked will be short. Duplicating the handle duplicates access | |||
to the locked regions. Access to the locked regions is not duplicated across | |||
the EXEC system call. Exiting with a file open and having issued locks on | |||
that file has undefined results. | |||
Programs that may be cancelled using INT 23H (File Size) or INT 24H (Set | |||
Relative Record Field) should trap these and release the locks before | |||
exiting. The proper method for using locks is not to rely on being denied | |||
read or write access, but to attempt to lock the region desired and examining | |||
the error code. | |||
AL = 01H UNLOCK | |||
Unlock releases the lock issued in the lock system call. The region | |||
specified must be exactly the same as the region specified in the previous | |||
lock. Closing a file with locks still in force has undefined results. | |||
Exiting with a file open and having issued locks on that file has undefined | |||
results. | |||
Programs that may be aborted using INT 23H (File Size) or INT 24H (Set | |||
Relative Record Field) should trap these and release the lock before exiting. | |||
The proper method for using locks is not to rely on being denied read or | |||
write access, but attempting to lock the region desired and examining the | |||
error code. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. Refer to "Responding to Errors" on page B-5 and "Extended Error | |||
Codes" on page B-5 for more information on the codes returned from function | |||
call 59H. | |||
5E00H -- | |||
GET MACHINE NAME | |||
PURPOSE | |||
Returns the character identifier of the local computer. | |||
EXAMPLE | |||
MOV AX,SEG CNAME ; Name buffer | |||
MOV DS,AX | |||
MOV DX OFFSET CNAME | |||
MOV AX,5E00H ; Function Call -- | |||
; Get Machine Name | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV NameFlag,CH ; Save name number indicator | |||
MOV NameID,CL ; Save NETBIOS name number | |||
CName DB "???????????????",0 ; ASCIIZ computer name | |||
NameFlag DB ? ; 0 = Name is not set | |||
; 1 = Name is set | |||
NameID DB ? ; NETBIOS name number | |||
COMMENTS | |||
Get Machine Name returns the text of the current computer name to the caller. | |||
The computer name is a 15-character byte string padded with spaces and | |||
followed by a 00H byte. If the computer name was never set, register CH is | |||
returned with 00H and the value in the CL register is invalid. The IBM PC | |||
Local Area Network program must be loaded for the function call to execute | |||
properly. | |||
5E02H -- | |||
SET PRINTER SETUP | |||
PURPOSE | |||
Specifies an initial string for printer files. | |||
EXAMPLE | |||
MOV AX,5E02H ; Function Call -- | |||
; Set Printer Setup | |||
MOV BX,Index ; Redirection List Index | |||
MOV CX,size ; String size | |||
MOV SI,SEG String ; String Buffer | |||
MOV DS,SI | |||
MOV SI,OFFSET String | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
Index DW ? ; Redirection List Index | |||
Size DW N ; String size (Maximum 64) | |||
String DB N DUP(?) ; Printer Setup String | |||
COMMENTS | |||
The string specified is put in front of all files destined for a particular | |||
network printer. Set Printer Setup allows multiple users of a single printer | |||
to specify their own mode of operation for the printer. BX is set to the | |||
same index that is used in function call 5F02H (Get Redirection List Entry). | |||
An error code is returned if print redirection is paused or if the IBM PC | |||
Local Area Network program is not loaded. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. Refer to "Responding to Errors" on page B-5 and "Extended Error | |||
Codes" on page B-5 for more information on the codes returned from function | |||
call 59H. | |||
IMPORTANT: The redirection index value may change if function call 5F03H | |||
(Redirect Device) or function call 5F04H (Cancel Redirection) is issued | |||
between the time the redirection list is scanned and the function call 5E02H | |||
(Set Printer Setup) is issued. Therefore, we recommend that you issue Set | |||
Printer Setup immediately after you issue "Get Redirection List ." | |||
5E03H -- | |||
GET PRINTER SETUP | |||
PURPOSE | |||
Returns the printer setup string for printer files. | |||
EXAMPLE | |||
MOV AX,5E03H ; Function Call -- | |||
; Get Printer Setup | |||
MOV BX,Index ; Redirection List Index | |||
MOV CX,SEG String ; String Buffer | |||
MOV ES,CX | |||
MOV DI,OFFSET String | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV Ssize, CX ; Save String size | |||
Index DW ? ; Redirection List Index | |||
Ssize DW ? ; String size | |||
String DB 64 DUP(?) ; Printer Setup String | |||
COMMENTS | |||
This function call returns the printer setup string which was specified using | |||
the function call 5E02H (Set Printer Setup). The setup string is attached to | |||
all files destined for a particular printer. The value in BX is set to the | |||
same index issued in function call 5F02H (Get Redirection List). Error code | |||
1 (invalid function number) is returned if the IBM PC Local Area Network is | |||
not loaded. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. Refer to "Responding to Errors" on page B-5 and "Extended Error | |||
Codes" on page B-5 for more information on the codes returned from function | |||
call 59H. | |||
IMPORTANT: The redirection index value may change if function call 5F03H | |||
(Redirect Device) or function call 5F04H (Cancel Redirection) is issued | |||
between the time the redirection list is scanned and the function call 5E03H | |||
(Get Printer Setup) is issued. Therefore, we recommend that you issue "Get | |||
Printer Setup" immediately after you issue "Get Redirection List." | |||
5F02H -- | |||
GET REDIRECTION LIST ENTRY | |||
PURPOSE | |||
Returns nonlocal network assignments. | |||
EXAMPLE | |||
MOV BX,0 ; Start at beginning of list | |||
Get_Loop: ; Get next entry | |||
MOV Index,BX ; Redirection list index | |||
MOV AX,5F02H ; Function Call -- | |||
; Get redirection list entry | |||
MOV SI,SEG device ; "PRN" is possible | |||
MOV DS,SI | |||
MOV SI,OFFSET device ; DS:SI points to local name | |||
MOV DI,SEG info | |||
MOV ES,DI | |||
MOV DI,OFFSET inf ; ES:DI points to buffer address of netwo | |||
PUSH BX | |||
PUSH DX ; Save registers | |||
PUSH BP | |||
INT 21H ; Issue request to DOS | |||
POP BP ; Restore registers | |||
POP DX | |||
JC CheckEnd ; Error code in AX | |||
MOV Status,BH ; Save status | |||
MOV Type,BL ; Save type | |||
MOV UserParm,CX ; Save user parmameter | |||
POP BX | |||
INC BX ; Set to next entry | |||
JMP Get_Loop | |||
CheckEnd: | |||
POP BX ; Balance state | |||
CMP AX,18 ; End of list? | |||
JNE Error ; No! | |||
Index DW ? ; Redirection list index (0 based) | |||
Device DB 128 DUP(?) ; ASCIIZ device name | |||
; example: "LPT1",0 | |||
; "A:",0 | |||
Status DB ? ; Device status | |||
; Bit 0=0 : Device is OK | |||
; Bit 0=1 : Device in Error | |||
; Bit 7-1 reserved | |||
UserParm DW ? ; User parameter | |||
Type DB ? ; Device type | |||
; 3 = NET USE device | |||
; 4 = NET USE drive | |||
Info DB 128 DUP(?) ; NET USE network path | |||
; example: "\\MYNODE\CDRIVE",0 | |||
COMMENTS | |||
The Get Redirection List Entry function call returns the list of network | |||
redirections that were created through function call 5F03H (Redirect Device). | |||
Each call returns one redirection, so BX should be increased by one each time | |||
to step through the list. The contents of the list may change between calls. | |||
The end-of-list is detected by error code 18 (no more files). Error code 1 | |||
(invalid function number) is returned if the IBM PC Local Area Network | |||
program is not loaded. | |||
If either disk or print redirection is paused, the function is not effected. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. Refer to "Responding to Errors" on page B-5 and "Extended Error | |||
Codes" on page B-5 for more information on the codes returned from function | |||
call 59H. | |||
5F03H -- | |||
REDIRECT DEVICE | |||
PURPOSE | |||
Causes a Redirector/Server connection to be made. | |||
EXAMPLE | |||
MOV AX,5F03H ; Function Call -- | |||
; Redirect Device | |||
MOV SI,SEG Device ; Device Buffer | |||
MOV DS,SI | |||
MOV SI,OFFSET Device | |||
MOV DI,SEG Net Path info ; Information Buffer | |||
MOV ES,DI | |||
MOV DI,OFFSET Net Path | |||
MOV BL,Type ; Set Type | |||
MOV CX,UserParm ; Set User Parameter | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
Device DB "....",0 ; ASCIIZ Device Name | |||
; example: "LPT1",0 | |||
; "A:",0 | |||
UserParm DW ? ; User Parameter | |||
Type DB ? ; Device Type | |||
; 3 = NET USE Device | |||
; 4 = NET USE Drive | |||
Net Path DB 128 DUP(0) | |||
COMMENTS | |||
This call defines the current directories for the network and defines | |||
redirection of network printers. | |||
If BL = 03, the source specifies a printer, the destination specifies a | |||
network path, and the CX register has a word that DOS 4.00 maintains for | |||
the programmer. For compatibility with the IBM PC Local Area Network | |||
program, CX should be set to 0. Values other than 0 are reserved for the | |||
IBM PC Local Area Network program. This word may be retrieved through | |||
function call 5F02H (Get Redirection List). All output destined for the | |||
specified printer is buffered and sent to the remote printer spool for | |||
that device. The printers are redirected at the INT 17H level. | |||
The source string must be PRN , LPT1, LPT2, or LPT3 each ended with a | |||
00H. The destination string must point to a network name string of the | |||
following form: | |||
[\\computername\¤shortname|printdevice‡] | |||
The destination string must be ended with a 00H. | |||
The ASCIIZ password (0 to 8 characters) for access to the remote device | |||
should immediately follow the network string. The password must end with | |||
a 00H. A null (0 length) password is considered to be no password. | |||
If BL = 4, the source specifies a drive letter and colon ending with 00H, | |||
the destination specifies a network path ending with 00H, and the CX | |||
register has a word that DOS maintains for the programmer. For | |||
compatibility with the IBM PC Local Area Network program, CX should be | |||
set to 00H. Values other than 00H are reserved for the IBM PC Local Area | |||
Network program. The value may be retrieved through function call 5F02H | |||
(Get Redirection List). If the source was a drive letter, the | |||
association is made between the drive letter and the network path. All | |||
subsequent references to the drive letter are translated to references to | |||
the network path. If the source is an empty string, the system attempts | |||
to grant access to the destination with the specified password without | |||
redirecting any device. | |||
The ASCIIZ password for access to the remote path should immediately | |||
follow the network string. A null (0 length) password ended with 00H is | |||
considered to be no password. | |||
Error codes are returned in AX. Issue function call 59H for additional | |||
information about the error class, suggested action, and location. Refer | |||
to "Responding to Errors" on page B-5 and "Extended Error Codes" on | |||
page B-5 for more information on the codes returned from function call | |||
59H (Get Extended Error) . | |||
NOTES: | |||
1. Devices redirected through this function call are not displayed by the | |||
NET USE command. | |||
2. An error is returned if you try to redirect a drive while disk | |||
redirection is paused, or if you try to redirect a printer while print | |||
redirection is paused. | |||
5F04H -- | |||
CANCEL REDIRECTION | |||
PURPOSE | |||
Cancels a previous redirection. | |||
EXAMPLE | |||
MOV AX,5F04H ; Function Call -- | |||
; Cancel redirection | |||
MOV SI,SEG Device ; Device buffer | |||
MOV DS,SI | |||
MOV SI,OFFSET Device | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
Device DB "....",0 ; ASCIIZ Device Name | |||
; example: "LPT1",0 | |||
; "A:",0 | |||
; "\\Computer\Path",0 | |||
COMMENTS | |||
The redirection created by the Redirect Device function call (5F03H) is | |||
removed through the Cancel Redirection call. If the buffer points to a drive | |||
letter and the drive is associated with a network name, the association is | |||
ended and the drive is restored to its physical meaning. If the buffer | |||
points to PRN, LPT1, LPT2, or LPT3, and the device has an association with a | |||
network device, the association is terminated and the device is restored to | |||
its physical meaning. If the buffer points to a network path ending with 00H | |||
and a password ending with 00H, the association between the local machine and | |||
the network directory is terminated. | |||
An error is returned if you try to cancel a redirected file device while disk | |||
redirection is paused, or if you try to cancel a redirected printer while | |||
print redirection is paused. Error code 1 (invalid function number) is | |||
returned if the IBM PC Local Area Network program is not loaded. | |||
Error codes are returned in AX. Issue function call 59H (Get Extended Error) | |||
for additional information about the error class, suggested action, and | |||
location. Refer to "Responding to Errors" on page B-5 and "Extended Error | |||
Codes" on page B-5 for more information on the codes returned from function | |||
call 59H. | |||
62H -- | |||
GET PROGRAM SEGMENT PREFIX ADDRESS | |||
PURPOSE | |||
Returns the program prefix address. | |||
EXAMPLE | |||
MOV AH,62H ; Function Call -- | |||
; Get Program Segment Prefix Address | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV PSPSeg,BX ; Save PSP address | |||
PSPSeg DW ? ; Segment address of my PSP | |||
COMMENTS | |||
The internal PSP address for the currently executing process is returned in | |||
BX. | |||
65H -- | |||
GET EXTENDED COUNTRY INFORMATION | |||
PURPOSE | |||
Returns extended country information. | |||
EXAMPLE | |||
; To get information | |||
MOV AH,65H ; Function Call -- | |||
; Get extended country information | |||
MOV AL,InfoID ; Data/function requested | |||
; (1, 2, 4, 6 or 7). | |||
MOV BX,CodePage ; Set desired code page | |||
; (-1=current, Set by function call 6602H). | |||
MOV CX,SizeBuffer ; Maximum data to return | |||
; (must be >= 5) | |||
MOV DX,CountryID ; Set desired Country ID | |||
; (-1=current, set by function call 38H). | |||
MOV DI,SEG Buffer ; Information return buffer | |||
MOV DS,DI | |||
MOV DI,OFFSET Buffer | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
Buffer LABEL BYTE | |||
; Format depends on AL value | |||
; AL=1 : Extended Country Information | |||
SizeBuffer DW ? ; Size of data block to return | |||
InfoID DB ? ; Type of info to get | |||
CIinfoSize DW ? ; amount of data that follows | |||
; (limited by CX input) | |||
CountryID DW ? ; Selected CountryID | |||
CodePage DW ? ; Selected Code Page | |||
; See function call 38H for the format of the remainder of this buffer | |||
; AL=2 : Upper Case Table | |||
DB 2 ; Indicates Upper Case Table | |||
UpperCase@ DD ? ; Address of Upper Case Table | |||
; AL=4 : File Upper Case Table | |||
DB 4 ; Indicates File Upper Case Table | |||
UpperCase@ DD ? ; Address of File Upper Case Table | |||
; AL=6 : Collating Table | |||
DB 6 ; Indicates Collate Table | |||
Collate@ DD ? ; Address of Collate Table | |||
; AL=7 : DBCS Vector Table | |||
DB 7 ; Indicates DBCS Vector Table | |||
DBCS@ DD ? ; Address of DBCS Vector Table | |||
COMMENTS | |||
On entry, DX contains the ID of the country for which the extended | |||
information is needed. AL contains the ID value for the country. | |||
If the country code and code page do not match, or if either one or both | |||
are invalid, an error code of 2 (file not found) is returned in AX. | |||
The size requested in CX must be 5 or greater. If it is less than 5, an | |||
error code of 1 is returned in AX. | |||
If the amount of information returned is greater than the size requested | |||
in CX, it is ended and no error is returned in AX. | |||
NOTE: For further information on the country information, see function call | |||
38H (Get or Set Country Dependent Information). | |||
The NLSFUNC DOS extension must be installed to get information for | |||
countries other than the Current Country. | |||
The uppercase table and the filename uppercase tables are 130 bytes long, | |||
consisting of a length field (2 bytes), followed by 128 uppercase values for | |||
the upper 128 ASCII characters. They have the following layout: | |||
Tsize DW 128 ; Table Size | |||
Table DB 128 DUP(?) ; Upper case versions of 80H to FFH | |||
The following formula can be used to determine the address of an uppercase | |||
equivalent for a lowercase character (ASCII in) in the uppercase table or the | |||
filename uppercase table. | |||
EXAMPLE | |||
ASCII in -(256-table len)+table start= address of ASCII out | |||
WHERE | |||
ASCII in = character to be generated | |||
table len = length of list of uppercase | |||
values (2 bytes) | |||
table start = starting address of uppercase | |||
table (4 bytes) | |||
ASCII out = uppercase value for ASCII in | |||
If the value of ASCII in is equal to or greater than (256-table len), there | |||
is an uppercase equivalent for ASCII in in the table. If it is lower than | |||
(256-table len), no uppercase equivalent exists in the table. | |||
The collate table is 258 bytes long, consisting of a length field (2 bytes) | |||
followed by 256 ASCII values, in the appropriate order. It has the following | |||
layout: | |||
Tsize DW 256 ; Table Size | |||
Table DB 256 DUP(?) ; Sort Weights for 00H to FFH | |||
The DBCS vector is variable in length, consisting of a length field (two | |||
bytes) followed by one or more pairs of bytes. It has the following layout: | |||
Tsize DW Nx2 ;List size | |||
1 DB Start,end ;DBCS vector 1 | |||
2 DB Start,end ;DBCS vector 2 | |||
: | |||
N DB Start,end ;DBCS vector n | |||
DB 0,0 ;End marker | |||
66H -- | |||
GET/SET GLOBAL CODE PAGE | |||
PURPOSE | |||
This function gets or sets the code page for the current country. | |||
MOV AX,6601H ; Function Call -- | |||
; Get Global Code Page | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV GlobalCP,BX ; Save Global Code Page | |||
MOV SystemCP,DX ; Save DOS System Code Page | |||
or | |||
MOV AX,6602H ; Function Call -- | |||
; Set Global Code Page | |||
MOV BX,GlobalCP ; New Global Code Page | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
GlobalCP DW ? ; Current Code Page of DOS Country Informati | |||
SystemCP DW ? ; Code Page of DOS messages | |||
; Often the default Code Page for the | |||
; current country | |||
COMMENTS | |||
DOS 4.00 moves the new code page data from the COUNTRY.SYS file to a resident | |||
country buffer area. DOS 4.00 uses the new code page to perform a Select to | |||
all attached devices that are set up for code page switching, (that is, have | |||
a code page switching device driver specified in CONFIG.SYS). If any device | |||
fails to be selected, an error code of 65 is returned in AX. The code page | |||
must be recognizable by the current country, and DOS 4.00 must be able to | |||
open and read from the country information file. Otherwise, the carry flag | |||
will be set on return and AX will contain 02 (file not found). | |||
NOTE: NLSFUNC must be installed to use this function call, and all the | |||
devices must be prepared in order for the Select function to be | |||
successful. | |||
67H -- | |||
SET HANDLE COUNT | |||
PURPOSE | |||
Permits more than 20 open files per process. | |||
EXAMPLE | |||
EntryPoint: | |||
MOV AH,62H ; Function Call -- | |||
; Get PSP Address | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV ES,BX ; Set Segment | |||
MOV AH,4AH ; Function Call -- | |||
; Set Memory Block Size | |||
MOV BX,paragraphs ; Set Size | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
MOV AH,67H ; Function Call - Set Handle Count | |||
MOV BX,NewHandles ; Set new handle count | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
NewHandles DW ? ; Number of Handles need | |||
; by this DOS 4.00 proce | |||
ListSize EQU (Endofprogram - EntryPoint) ; Number of bytes | |||
Paragraphs EQU (ListSize / 10H) ; Number of paragraphs | |||
End_of_program LABEL BYTE ; Last used position for | |||
; this program | |||
COMMENTS | |||
The maximum number of file handles allowed for this interrupt is 64KB. If | |||
the the specified number of allowable handles is less than the current number | |||
allowed, the specified number will become current only after all the handles | |||
above the specified number have been closed. If the specified number is less | |||
than 20, the number is assumed to be 20. Data base applications can use this | |||
function to reduce the need to swap handles. | |||
You must release memory for DOS 4.00 to contain the extended handle list. | |||
You can do this by using the SET BLOCK (4AH) function call. | |||
68H -- | |||
COMMIT FILE | |||
PURPOSE | |||
Causes all buffered data for a file to be written to the device. This | |||
function can be used instead of a close-open sequence. | |||
EXAMPLE | |||
MOV AH,68H ; Function Call -- Commit File | |||
MOV BX,Handle ; Select file | |||
INT 21H ; Issue request to DOS | |||
JC Error ; Error code in AX | |||
Handle DW ? ; Handle from previous Open or Create | |||
COMMENTS | |||
Commit File provides a faster and more secure method of committing data in | |||
multi-user environments such as the IBM PC Local Area Network. | |||
6CH -- | |||
EXTENDED OPEN/CREATE | |||
PURPOSE | |||
Optionally opens and creates a file. | |||
EXAMPLE | |||
MOV AH,6CH ; Extended open | |||
MOV AL,0 ; Reserved | |||
MOV BX,MODE ; Open mode | |||
; Format : 0WF00000ISSS0AAA | |||
; AAA=Access code 0=Read | |||
; 1=Write | |||
; 2=Read/Write | |||
; SSS=Sharing mode 0=Compatibility | |||
; 1=DenyRead/Write | |||
; 2=DenyWrite | |||
; 3=DenyRead | |||
; 4=DenyNone | |||
; I 0=Pass handle to chile, 1=No inherit | |||
; F 0=INT 24H, 1=Return error | |||
; on this open and any I/O to this handle | |||
; W 0=No commit, 1=Auto-Commit on write | |||
MOV CX,ATTR ; Create attribute (ignored if open) | |||
MOV DX,FLAG ; Function control, Format=0000000NNNNEEEE | |||
; NNNN=Does not exist action | |||
; 0=Fail, 1=Create | |||
; EEEE=Exists action | |||
; 0=Fail, 1=open, 2=Replace/Open | |||
MOV SI,SEG file name ; Name to open or create | |||
MOV DS,SI | |||
MOV SI,OFFSET file name | |||
INT 21H | |||
JC ERROR | |||
; AX=Handle | |||
; CX=Action taken code | |||
; 1=File opened | |||
; 2=File created/opened | |||
; 3=File replaced/opened | |||
;---- | |||
Mode DW ? ; Open mode bit | |||
; Definitions | |||
Attr DW ? ; File attributes | |||
Flag DW ? ; Function definition | |||
File name 64 DUP (0) | |||
COMMENTS | |||
Function 6CH combines the functions currently available with OPEN, CREATE and | |||
a CREATE NEW. | |||
If F is 1, the critical error handler (Interrupt 24) is disabled for the | |||
handle returned by Extended Open. Any I/O issued to this handle will never | |||
generate the critical error but only the extended error. | |||
If F is 0, no actions are taken. | |||
If W is 1, any disk write using the handle returned by Extended Open will | |||
accompany with a commit call (see Interrupt 21H (AL=68H)). | |||
If W is 0, no actions are taken. | |||
</PRE> | </PRE> | ||
[[Category:DOS Books]] | [[Category:DOS Books]] | ||
Revision as of 23:30, 14 July 2018
DOS 4.00: TECHNICAL REFERENCE AND APPLICATION PROGRAMMING
August 6th, 1988
FIRST EDITION (JULY 1988)
(c) Copyright International Business Machines Corporation 1981, 1988
All rights reserved.
PREFACE
AUDIENCE
This book is written for programmers who develop applications for IBM
Personal Computers and Personal System/2(R) computers.(1)
The program developer should be competent on the IBM Personal Computer and/or
the Personal System/2 and should be familiar with DOS and at least one
personal computer programming language.
CONTENT
Some parts of the book have been rewritten and reorganized to make reference
and system architecture information more concise and to present programming
information in a task-oriented manner. Information about new and enhanced
functions has been added, providing some guide material.
RELATED PUBLICATIONS
Other manuals that provide detailed information about DOS 4.00 are:
Getting Started with DOS 4.00
Using DOS 4.00
DOS 4.00 Command Reference
IBM Keyboard Layouts for Your PC and PS/2 systems.
(1) Personal System/2 is a registered trademark of the International Business
Machines Corporation.
CONTENTS
CHAPTER 1. INTRODUCTION TRD41 7
Organization of this Book TRD41 16
New DOS 4.00 Services TRD41 43
The Utilities Diskette TRD41 57
Minimum Hardware Configuration TRD41 79
CHAPTER 2. ACCESSING DISKS TRD42 11
The Disk Format TRD42 20
The Boot Record TRD42 41
The File Allocation Table (FAT) TRD42 49
The Disk Directory TRD42 114
The Data Area TRD42 143
Accessing the Disk TRD42 150
Reading and Writing Data Directly to the Disk TRD42 168
Requesting Drive and Disk Information TRD42 180
CHAPTER 3. ACCESSING FILES WITH FILE HANDLES TRD43 13
Filenames TRD43 48
File Handles TRD43 62
Special File Handles TRD43 88
Reading and Writing Data to a File TRD43 119
Requesting and Specifying File Attributes TRD43 140
Accessing Subdirectories TRD43 152
Accessing Directories TRD43 266
Finding Files in Directories TRD43 282
Requesting and Specifying National Language Support (NLS) TRD43 294
Controlling Network Operations TRD43 307
CHAPTER 4. ACCESSING FILES USING FILE CONTROL BLOCKS TRD44 10
The File Control Block (FCB) TRD44 21
The Extended FCB TRD44 128
The Disk Transfer Area (DTA) TRD44 149
Accessing Files TRD44 172
Accessing Sequential Records TRD44 218
Accessing Random Records TRD44 231
Finding Files in Directories TRD44 250
CHAPTER 5. MANAGING DEVICE I/O TRD45 9
Managing Display I/O TRD45 20
Managing Keyboard I/O TRD45 43
Managing Miscellaneous I/O TRD45 71
Managing File System Activities TRD45 84
Accessing the System Device Drivers' Control Channel TRD45 105
Reading and Writing Data in Binary and ASCII Modes TRD45 155
CHAPTER 6. CONTROLLING PROCESSES TRD46 17
Allocating Memory TRD46 32
DOS 4.00 Memory Management TRD46 47
The DOS 4.00 Memory Map TRD46 71
Identifying a Program at Load Time TRD46 134
The Program Segment TRD46 147
Loading and Executing Overlays TRD46 198
The Parameter Block TRD46 216
Terminating a Program/Subprogram TRD46 260
Loading an Overlay without Executing It TRD46 307
Calling a Command Processor TRD46 328
Responding to Errors TRD46 352
Responding to a Control-Break Action TRD46 379
Requesting and Specifying the System Date and Time TRD46 411
Requesting and Specifying the Interrupt Vectors TRD46 426
CHAPTER 7. CREATING OBJECT CODE LIBRARIES TRD47 15
The IBM Library Manager/2 TRD47 20
Starting the LIB.EXE Utility TRD47 52
Entering Input at the Command Line TRD47 216
Using a Response File TRD47 308
Creating and Maintaining Libraries TRD47 359
Creating a Library File TRD47 364
Modifying a Library File TRD47 395
Combining Libraries TRD47 457
Creating a Cross-Reference Listing TRD47 475
Performing Consistency Checks TRD47 500
Setting the Library Page Size TRD47 513
Library Manager Error Messages TRD47 540
CHAPTER 8. CREATING AN EXECUTABLE FILE TRD48 35
The IBM Linker/2 TRD48 40
Starting the LINK.EXE Program TRD48 56
Entering LINK Input at the Command Line TRD48 246
Using a Response File to Supply LINK Input TRD48 340
Using Linker Options TRD48 436
Preparing Files for CodeView /CODEVIEW TRD48 512
Reserving Paragraph Space /CPARMAXALLOC TRD48 530
Ordering Segments /DOSSEG TRD48 560
Controlling Data Loading /DSALLOCATE TRD48 583
Packing Executable Files /EXEPACK TRD48 607
Viewing the Options List /HELP TRD48 640
Controlling Run File Loading /HIGH TRD48 661
Displaying LINK-Time Information /INFORMATION TRD48 679
Copying Line Numbers to the Map File /LINENUMBERS TRD48 692
Producing a Public Symbol Map /MAP TRD48 731
Ignoring Default Libraries /NODEFAULTLIBRARYSEARCH TRD48 770
Preserving Compatibility /NOGROUPASSOCIATION TRD48 793
Preserving Lowercase /NOIGNORECASE TRD48 807
Setting the Overlay Interrupt /OVERLAYINTERRUPT TRD48 836
Pausing to Change Disks /PAUSE TRD48 856
Setting the Maximum Number of Segments /SEGMENTS TRD48 900
Setting the Stack Size /STACK TRD48 939
Reading the Map File TRD48 976
Creating an Overlaid Version of Your Program TRD48 1032
Specifying an Overlay Structure to LINK TRD48 1050
How LINK Formats the .EXE File TRD48 1075
Ordering Segments TRD48 1083
Segment Combine-Types TRD48 1106
Groups TRD48 1143
Instruction and Data Reference Errors TRD48 1159
Linker Error Messages TRD48 1215
Linker Limits TRD48 1681
CHAPTER 9. CONVERTING FILE FORMATS TRD49 8
The EXE2BIN.EXE Utility TRD49 13
Entering Input to EXE2BIN TRD49 34
Two Types of Conversion TRD49 61
Device Drivers TRD49 66
Standard .COM File TRD49 100
CHAPTER 10. DEBUGGING A PROGRAM TRD410 32
The DEBUG Utility TRD410 37
Starting the DEBUG.COM Program TRD410 46
Entering Commands at the DEBUG Prompt TRD410 67
DEBUG Command Summary TRD410 103
The DEBUG Work Space TRD410 181
A (Assemble) Command TRD410 225
C (Compare) Command TRD410 348
D (Dump) Command TRD410 400
E (Enter) Command TRD410 504
F (Fill) Command TRD410 620
G (Go) Command TRD410 669
H (Hexarithmetic) Command TRD410 771
I (Input) Command TRD410 789
L (Load) Command TRD410 811
M (Move) Command TRD410 919
N (Name) Command TRD410 973
O (Output) Command TRD410 1019
P (Proceed) Command TRD410 1040
Q (Quit) Command TRD410 1090
R (Register) Command TRD410 1113
S (Search) Command TRD410 1263
T (Trace) Command TRD410 1321
U (Unassemble) Command TRD410 1390
W (Write) Command TRD410 1513
XA (EMS Allocate) Command TRD410 1645
XD (EMS Deallocate) Command TRD410 1672
XM (EMS Map) Command TRD410 1699
XS (EMS Status) Command TRD410 1727
DEBUG Error Messages TRD410 1759
CHAPTER 11. WRITING AN INSTALLABLE DEVICE DRIVER TRD411 26
Types of Device Drivers TRD411 39
Character Device Drivers TRD411 48
Block Device Drivers TRD411 55
How DOS 4.00 Installs Device Drivers TRD411 84
The Basic Parts of a Device Driver TRD411 134
The Device Driver Header TRD411 148
The Strategy Routine TRD411 274
The Interrupt Routines TRD411 283
How DOS 4.00 Passes a Request TRD411 300
Responding to Requests TRD411 392
Initialization Request TRD411 456
Media Check Request TRD411 511
Build BPB Request TRD411 630
Input and Output Requests TRD411 815
Nondestructive Input No Wait Request TRD411 879
Character Input and Output Status Requests TRD411 901
Character Input and Output Flush Requests TRD411 935
Open and Close Requests TRD411 951
Removable Media Request TRD411 983
Generic IOCTL Request TRD411 1008
Get Logical Device Request TRD411 1037
Set Logical Device Request TRD411 1055
CLOCK$ Device Driver Example TRD411 1073
APPENDIX A. DOS 4.00 INTERRUPTS TRD412 13
20H Program Terminate TRD412 21
21H Function Request TRD412 41
22H Terminate Address TRD412 46
23H Ctrl-Break Exit Address TRD412 53
24H Critical Error Handler Vector TRD412 83
25H/26H Absolute Disk Read/Write TRD412 287
27H Terminate but Stay Resident TRD412 353
28H-2EH Reserved for DOS 4.00 TRD412 392
2FH Multiplex Interrupt TRD412 396
30H-3FH Reserved for DOS 4.00 TRD412 695
APPENDIX B. DOS 4.00 FUNCTION CALLS TRD413 100
Using DOS 4.00 Function Calls TRD413 219
Program Code Fragments TRD413 230
.COM Programs TRD413 236
DOS 4.00 Registers TRD413 256
Responding to Errors TRD413 340
Extended Error Codes TRD413 355
00H -- Program Terminate TRD413 518
01H -- Console Input with Echo TRD413 546
02H -- Display Output TRD413 581
03H -- Auxiliary Input TRD413 603
04H -- Auxiliary Output TRD413 631
05H -- Printer Output TRD413 655
06H -- Direct Console I/O TRD413 672
07H -- Direct Console Input Without Echo TRD413 720
08H -- Console Input Without Echo TRD413 753
09H -- Display String TRD413 786
0AH -- Buffered Keyboard Input TRD413 815
0BH -- Check Standard Input Status TRD413 848
0CH -- Clear Keyboard Buffer and Invoke a Keyboard Function TRD413 868
0DH -- Disk Reset TRD413 885
0EH -- Select Disk TRD413 904
0FH -- Open File TRD413 937
10H -- Close File TRD413 985
11H -- Search for First Entry TRD413 1022
12H -- Search for Next Entry TRD413 1099
13H -- Delete File TRD413 1149
14H -- Sequential Read TRD413 1193
15H -- Sequential Write TRD413 1240
16H -- Create File TRD413 1286
17H -- Rename File TRD413 1330
19H -- Current Disk TRD413 1380
1AH -- Set Disk Transfer Address TRD413 1400
1BH -- Allocation Table Information TRD413 1425
1CH -- Allocation Table Information for Specific Device TRD413 1453
21H -- Random Read TRD413 1489
22H -- Random Write TRD413 1541
23H -- File Size TRD413 1599
24H -- Set Relative Record Field TRD413 1642
25H -- Set Interrupt Vector TRD413 1668
26H -- Create New Program Segment TRD413 1695
27H -- Random Block Read TRD413 1725
28H -- Random Block Write TRD413 1787
29H -- Parse Filename TRD413 1847
2AH -- Get Date TRD413 1918
2BH -- Set Date TRD413 1946
2CH -- Get Time TRD413 1979
2DH -- Set Time TRD413 2015
2EH -- Set/Reset Verify Switch TRD413 2051
2FH -- Get Disk Transfer Address (DTA) TRD413 2085
30H -- Get DOS Version Number TRD413 2108
31H -- Terminate Process and Remain Resident TRD413 2138
33H -- Get/Set System Value TRD413 2175
35H -- Get Interrupt Vector TRD413 2235
36H -- Get Disk Free Space TRD413 2262
38H -- Get or Set Country Dependent Information TRD413 2318
39H -- Create Subdirectory (MKDIR) TRD413 2431
3AH -- Remove Subdirectory (RMDIR) TRD413 2466
3BH -- Change the Current Directory (CHDIR) TRD413 2498
3CH -- Create a File (CREAT) TRD413 2530
3DH -- Open a File TRD413 2577
3EH -- Close a File Handle TRD413 2812
3FH -- Read from a File or Device TRD413 2840
40H -- Write to a File or Device TRD413 2886
41H -- Delete a File from a Specified Directory (UNLINK) TRD413 2938
42H -- Move File Read Write Pointer (LSEEK) TRD413 2971
43H -- Change File Mode (CHMOD) TRD413 3035
44H -- I/O Control for Devices TRD413 3092
45H -- Duplicate a File Handle (DUP) TRD413 3103
46H -- Force a Duplicate of a Handle (FORCDUP) TRD413 3137
47H -- Get Current Directory TRD413 3170
48H -- Allocate Memory TRD413 3202
49H -- Free Allocated Memory TRD413 3237
4AH -- Modify Allocated Memory Blocks (SETBLOCK) TRD413 3263
4BH -- Load or Execute a Program (EXEC) TRD413 3303
4CH -- Terminate a Process (EXIT) TRD413 3442
4DH -- Get Return Code of a Subprocess (WAIT) TRD413 3466
4EH -- Find First Matching File (FIND FIRST) TRD413 3494
4FH -- Find Next Matching File (FIND NEXT) TRD413 3567
54H -- Get Verify Setting TRD413 3606
56H -- Rename a File TRD413 3628
57H -- Get/Set File's Date and Time TRD413 3669
59H -- Get Extended Error TRD413 3714
5AH -- Create Unique File TRD413 3785
5BH -- Create New File TRD413 3839
5CH -- Lock/Unlock File Access TRD413 3878
5E00H -- Get Machine Name TRD413 3972
5E02H -- Set Printer Setup TRD413 4006
5E03H -- Get Printer Setup TRD413 4051
5F02H -- Get Redirection List Entry TRD413 4096
5F03H -- Redirect Device TRD413 4169
5F04H -- Cancel Redirection TRD413 4259
62H -- Get Program Segment Prefix Address TRD413 4305
65H -- Get Extended Country Information TRD413 4328
66H -- Get/Set Global Code Page TRD413 4451
67H -- Set Handle Count TRD413 4494
68H -- Commit File TRD413 4539
6CH -- Extended Open/Create TRD413 4562
APPENDIX C. I/O CONTROL FOR DEVICES (IOCTL) TRD414 4
44H -- I/O Control for Devices (IOCtl) TRD414 50
APPENDIX D. EXPANDED MEMORY SUPPORT TRD415 3
Chapter 1
CHAPTER 1. INTRODUCTION 7 Organization of this Book 16 New DOS 4.00 Services 43 The Utilities Diskette 57 Minimum Hardware Configuration 79
CHAPTER 1. INTRODUCTION
This chapter provides information about this book, including the following:
Organization of the book for quick information retrieval
New and enhanced DOS 4.00 services
Contents of the utilities diskette
Minimum hardware configuration.
ORGANIZATION OF THIS BOOK
This book is organized by logical application program development stages necessary to develop an application program on DOS 4.00. You must:
Write the source code for the program
Translate the source code to executable code
Load and execute the program
Debug the program
Create object code libraries (optional)
Convert your file formats (optional).
In addition, the book tells how to make best use of the operating system by writing your own device driver or by using the system extensions.
Each chapter describes a particular subject. You do not need to read the entire book to create programs or solve problems. Key topics also can be found by referring to the index and the table of contents.
The appendixes contain reference information for quick retrieval. They contain the entire numerical list of DOS 4.00 services, including interrupts, function calls, and device driver services.
The Technical Quick Reference contains abbreviated information about interrupts. Function calls are listed, along with input/output information and error codes.
NEW DOS 4.00 SERVICES
DOS 4.00 replaces IBM DOS Version 3.30 and incorporates all services previously provided by IBM DOS Version 3.30. Major new features include:
Enhanced country support
Double-byte character support
A device driver
File system support of large disk media
Extended Memory Support (EMS)
Performance improvements to the file system.
Several function requests within interrupt 21H have been enhanced.
THE UTILITIES DISKETTE
A utilities diskette is included with this book. It contains a listing of the following utilities, and the description of each utility, to help programmers develop an application program:
DEBUG.COM A utility to isolate and determine errors in executable programs.
EXE2BIN.EXE A utility to convert executable file formats (.EXE) to .COM formats to make them more compact and, therefore, load more quickly.
LIB.EXE A utility that allows the programmer to build and edit object libraries.
LINK.EXE A utility to translate object code to executable code.
VDISK.ASM A fully documented programming example of a device driver. However, this example does not reflect the current level of VDISK.SYS.
MINIMUM HARDWARE CONFIGURATION
DOS 4.00 supports the following family of IBM Personal Computers and Personal System/2 computers:
The IBM Personal Computer The IBM Personal Computer XT(TM) The IBM Personal Computer XT(TM) Model 286(1) The IBM Personal Computer AT(R) (all versions)(2) The IBM PC Convertible The IBM Personal System/2(R) Model 25 (all versions) The IBM Personal System/2(R) Model 30 (all versions) The IBM Personal System/2(R) Model 50 (all versions) The IBM Personal System/2(R) Model 60 (all versions) The IBM Personal System/2(R) Model 80 (all versions).
NOTE: DOS 4.00 does not support the IBM PCjr.
The minimum memory requirement is 256KB.
(1) Personal Computer XT is a trademark of the International Business
Machines Corporation.
(2) Personal Computer AT and Personal System/2 are registered trademarks of the International Business Machines Corporation.
PART 1. WRITING PROGRAMS
Chapter 10
CHAPTER 10. DEBUGGING A PROGRAM 32
The DEBUG Utility 37
Starting the DEBUG.COM Program 46
Entering Commands at the DEBUG Prompt 67
DEBUG Command Summary 103
The DEBUG Work Space 181
A (Assemble) Command 225
C (Compare) Command 348
D (Dump) Command 400
E (Enter) Command 504
F (Fill) Command 620
G (Go) Command 669
H (Hexarithmetic) Command 771
I (Input) Command 789
L (Load) Command 811
M (Move) Command 919
N (Name) Command 973
O (Output) Command 1019
P (Proceed) Command 1040
Q (Quit) Command 1090
R (Register) Command 1113
S (Search) Command 1263
T (Trace) Command 1321
U (Unassemble) Command 1390
W (Write) Command 1513
XA (EMS Allocate) Command 1645
XD (EMS Deallocate) Command 1672
XM (EMS Map) Command 1699
XS (EMS Status) Command 1727
DEBUG Error Messages 1759
CHAPTER 10. DEBUGGING A PROGRAM
This chapter describes how to use the DEBUG.COM program on the utilities
diskette to identify and fix problems in your programs.
THE DEBUG UTILITY
DEBUG provides a controlled testing environment that enables you to monitor
the execution of a program. You can make changes directly to a .COM or an
.EXE file and execute the file immediately to determine whether your changes
fixed a problem. You do not need to reassemble source code files first.
DEBUG allows you to load, alter, or display any file and to execute object
files as well.
STARTING THE DEBUG.COM PROGRAM
To start DEBUG, enter information in the following format:
You can enter just the DEBUG command, or you can include a file
specification. The parameters parm1 and parm2 represent input and output
specifications of the program you are debugging. For example, suppose you
wanted to monitor the execution of the DOS 4.00 DISKCOMP utility. You enter:
DEBUG DISKCOMP.COM A: B:
The DEBUG program loads DISKCOMP into memory and displays the DEBUG prompt:
The hyphen (-) tells you DEBUG is ready to accept commands to alter, display,
or execute the contents of the program in memory.
If you enter just DEBUG without a file specification, you can either work
with the present memory contents or you can load a required file into memory
using the DEBUG NAME and LOAD commands.
ENTERING COMMANDS AT THE DEBUG PROMPT
A DEBUG command consists of a single letter, usually followed by one or more
parameters. For example, the NAME command is entered at the DEBUG prompt as
a single letter followed by a file specification:
-N MYPROG
A command and its parameters can be entered in uppercase, lowercase, or a
combination of both. The command and its parameters can be separated by
delimiters; however, delimiters are only required between two consecutive
hexadecimal values. Thus, the following DUMP commands are equivalent:
dcs:100 110
d cs:100 110
d,cs:100,110
A command is activated only after you press the Enter key. If you want to
terminate a command and return to the DEBUG prompt, simultaneously press the
Ctrl and Break keys.
For commands producing a large amount of output, you can simultaneously press
the Ctrl and Num Lock keys (or Pause key if available) to suspend the display
and then press any key to restart the display, or you can redirect the
command's output to a file.
When DEBUG encounters a syntax error in a line, it displays the line with the
error identified as follows:
d cs:100 CS:100
&hat.error 110
In this example, the DUMP command expects the second address to contain only
a hexadecimal offset value. It finds the S, which is not a hexadecimal
character.
DEBUG COMMAND SUMMARY
The table below lists the DEBUG commands and describes the debugging
operations you can perform with them. Complete format descriptions and
examples for each command can be found starting on page 10-4.
+---------------------------------------------------------------------------+
| COMMAND TASK DESCRIPTION |
+---------------------------------------------------------------------------+
| A Assemble IBM Macro Assembler statements directly into memory. |
| (Assemble) |
+---------------------------------------------------------------------------+
| C Compare the contents of two blocks of memory. |
| (Compare) |
+---------------------------------------------------------------------------+
| D (Dump) Dump the contents of a portion of memory to the display or |
| redirect it to a file. |
+---------------------------------------------------------------------------+
| E (Enter) Make changes to bytes in memory. |
+---------------------------------------------------------------------------+
| F (Fill) Fill a range of memory with byte values. |
+---------------------------------------------------------------------------+
| G (Go) Execute the program in memory from one address to the |
| breakpoint address and then display the next instruction. |
+---------------------------------------------------------------------------+
| H (Hex) Add and subtract two hexadecimal values and display the |
| results. |
+---------------------------------------------------------------------------+
| I (Input) Display the input in the first byte next to the port. |
+---------------------------------------------------------------------------+
+---------------------------------------------------------------------------+
| COMMAND TASK DESCRIPTION |
+---------------------------------------------------------------------------+
| L (Load) Load the contents of absolute disk sectors or a file |
| specified by the NAME command into memory. |
+---------------------------------------------------------------------------+
| M (Move) Copy the contents of a block of memory to another location. |
+---------------------------------------------------------------------------+
| N (Name) Set up file control blocks and file specification information |
| for LOAD and WRITE commands. |
+---------------------------------------------------------------------------+
| O (Output) Send a byte to an output port. |
+---------------------------------------------------------------------------+
| P Execute a subroutine call, loop instruction, interrupt, or |
| (Proceed) repeat string instruction and return control to DEBUG at the |
| next instruction. |
+---------------------------------------------------------------------------+
| Q (Quit) End the DEBUG session without saving the debugged program. |
+---------------------------------------------------------------------------+
| R Display the contents of registers and the settings of flags. |
| (Register) |
+---------------------------------------------------------------------------+
| S (Search) Search a range of memory for characters. |
+---------------------------------------------------------------------------+
| T (Trace) Execute one or more instructions in your program and display |
| the contents of registers and flags after each instruction. |
+---------------------------------------------------------------------------+
| U Translate the contents of memory into Assembler-like |
| (Unassemble)statements, displaying their addresses and hexadecimal |
| values. |
+---------------------------------------------------------------------------+
| W (Write) Write the debugged program to absolute disk sectors or to the |
| original file loaded with DEBUG. |
+---------------------------------------------------------------------------+
| XA Allocate a specified number of expanded memory pages to an |
| (Allocate) EMS handle. |
+---------------------------------------------------------------------------+
| XD Deallocate an EMS handle. |
| (Deallocate) |
+---------------------------------------------------------------------------+
| XM (Map) Map an EMS logical page to an EMS physical page from an EMS |
| handle. |
+---------------------------------------------------------------------------+
| XS Display the status of expanded memory. |
| (Status) |
+---------------------------------------------------------------------------+
THE DEBUG WORK SPACE
When the DEBUG program starts, the registers and flags are set to the
following values for the program being debugged:
The segment registers (CS, DS, ES, and SS) are set to the bottom of free
memory; that is, the first segment after the end of the DEBUG program.
The Instruction Pointer (IP) is set to hex 0100.
The Stack Pointer (SP) is set to the end of the segment, or the bottom of
the transient portion of the program loader, whichever is lower. The
segment size at offset 6 is reduced by hex 100 to allow for a stack that
size.
The remaining registers (AX, BX, CX, DX, BP, SI, and DI) are set to 0.
However, if you start the DEBUG program with a file specification, the CX
register contains the length of the file in bytes. If the file is
greater than 64KB, the length is contained in registers BX and CX (the
high portion in BX).
The initial state of the flags is:
NV UP EI PL NZ NA PO NC
The default disk transfer address is set to hex 80 in the code segment.
All of available memory is allocated. At this point, the loaded program is
unable to allocate memory.
.EXE Files
If a file loaded by DEBUG has an extension of .EXE, DEBUG does the necessary
relocation and sets the segment registers, stack pointer, and instruction
pointer to the values defined in the file. The DS and ES registers, however,
point to the program segment prefix at the lowest available segment. The BX
and CX registers contain the size of the program that is smaller than the
file size.
The program is loaded at the high end of memory if the appropriate parameter
was specified when the linker created the file.
.HEX Files
If a file loaded by DEBUG has an extension of .HEX, the file is assumed to be
in INTEL hex format, and is converted to executable form while being loaded.
A (ASSEMBLE) COMMAND
PURPOSE
Assembles IBM Macro Assembler language statements directly into memory.
FORMAT
A[address]
PARAMETERS
address Use any of the following formats:
A segment register plus an offset, such as CS:0100
A segment address plus an offset, such as 4BA:0100
An offset only, such as 100. In this case, the default
segment is used.
COMMENTS
All numeric input to the Assemble command is in hexadecimal. The assembly
statements you enter are assembled into memory at successive locations,
starting with the address specified in address. If no address is specified,
the statements are assembled into the area at CS:0100, if no previous
Assemble command was used, or into the location following the last
instruction assembled by a previous Assemble command. After all desired
statements have been entered, press the Enter key when you are prompted for
the next statement to return to the DEBUG prompt.
DEBUG responds to invalid statements by displaying:
&hat.error
and re-displaying the current assemble address.
DEBUG supports standard 8086/8088 assembly language syntax (and the 8087
instruction set), with the following rules:
All numeric values entered are hexadecimal and can be entered as 1
through 4 characters.
Prefix mnemonics are entered in front of the opcode to which they refer.
They can also be entered on a separate line.
The segment override mnemonics are CS:, DS:, ES:, and SS:.
String manipulation mnemonics must specify the string size. For example,
MOVSW must be used to move word strings and MOVSB must be used to move
byte strings.
The mnemonic for the far return is RETF.
The assembler will automatically assemble short, near, or far jumps and
calls depending on byte displacement to the destination address. These
can be overridden with the NEAR or FAR prefix. For example:
0100:0500 JMP 502 ;a 2 byte short jump
0100:0502 JMP NEAR 505 ;a 3 byte near jump
0100:0505 JMP FAR 50A ;a 5 byte far jump
The NEAR prefix can be abbreviated to NE, but the FAR prefix cannot be
abbreviated.
DEBUG cannot tell whether some operands refer to a word memory location
or a byte memory location. In this case, the data type must be
explicitly stated with the prefix WORD PTR or BYTE PTR. DEBUG will also
accept the abbreviations WO and BY. For example:
NEG BYTE PTR [128]
DEC WO [SI]
DEBUG also cannot tell whether an operand refers to a memory location or
to an immediate operand. DEBUG uses the common convention that operands
enclosed in square brackets refer to memory. For example:
MOV AX,21 ;Load AX with 21H
MOV AX,[21] ;Load AX with the
contents of memory
location 21H
Two popular pseudo-instructions have also been included. The DB opcode
assembles byte values directly into memory. The DW opcode assembles word
values directly into memory. For example:
DB 1,2,3,4,'THIS IS AN EXAMPLE'
DB 'THIS IS A QUOTE: ''
DB 'THIS IS AN APOSTROPHE:''
DW 1000,2000,3000,'BACH:'
All forms of the register indirect commands are supported. For example:
ADD BX,34[BP+2][SI-1]
POP [BP+DI]
PUSH [SI]
All opcode synonyms are supported. For example:
LOOPZ 100
LOOPE 100
JA 200
JNBE 200
For numeric co-processor opcodes the WAIT or FWAIT prefix must be
explicitly specified. For example:
FWAIT FADD ST,ST(3) ;This line will
;assemble a
;FWAIT prefix
FLD TBYTE PTR [BX] ;This line will
;not
EXAMPLE
C>debug
-a200
08B4:0200 xor ax,ax
08B4:0202 mov [bx],ax
08B4:0204 ret
08B4:0205
C (COMPARE) COMMAND
PURPOSE
Compares the contents of two blocks of memory.
FORMAT
C range address
PARAMETERS
range Either of these two formats:
An address followed by an offset, such as CS:100 110.
An address followed by L value, where value is the number of
hexadecimal bytes to be processed. For example, CS:100 L 10.
The limit for range is hexadecimal 10000 or decimal 64KB. To
specify a range of 64KB within 4 hexadecimal characters, enter
0000 or 0 for value.
address Any of these three formats:
A segment register plus an offset, such as CS:0100.
A segment address plus an offset, such as 4BA:0100.
An offset only, such as 100. In this case, the default
segment is used.
COMMENTS
The contents of the two blocks of memory are compared; the length of the
comparison is determined from the range. If unequal bytes are found, their
addresses and contents are displayed, in the form:
addr1 byte1 byte2 addr2
where, the first half (addr1 byte1) refers to the location and contents of
the mismatching locations in range, and the second half (byte2 addr2) refers
to the byte found in address.
If you enter only an offset for the beginning address of range, the C command
assumes the segment contained in the DS register. To specify an ending
address for range, enter it with only an offset value.
EXAMPLE
C 100 L20 200
The 32 bytes (hex 20) of memory beginning at DS:100 are compared with the 32
bytes beginning at DS:200. L20 is the range.
D (DUMP) COMMAND
PURPOSE
Displays the contents of a portion of memory.
FORMAT
D [address]
or
D [range]
PARAMETERS
address Any of the following formats:
A segment register plus an offset, such as CS:0100.
A segment address plus an offset, such as 4BA:0100.
An offset only, such as 100. In this case, the default
segment is used.
range Either of these two formats:
An address followed by an offset, such as CS:100 110.
An address followed by L value, where value is the number of
hexadecimal bytes to be processed. For example, CS:100 L 10.
The limit for range is hexadecimal 10000 or decimal 64K bytes.
To specify a range of 64K bytes within 4 hexadecimal characters,
enter 0000 or 0 for value.
COMMENTS
The dump is displayed in two parts:
1. A hexadecimal portion. Each byte is displayed in hexadecimal.
2. An ASCII portion. The bytes are displayed as ASCII characters.
Unprintable characters (ASCII 0 to 31 and 127 to 255) are indicated by a
period.
With a 40-column system display format, each line begins on an 8-byte
boundary and shows 8 bytes.
With an 80-column system display format, each line begins on a 16-byte
boundary and shows 16 bytes. There is a hyphen between the 8th and 9th
bytes.
NOTE: The first line may have fewer than 8 or 16 bytes if the starting
address of the dump is not on a boundary. In this case, the second
line of the dump begins on a boundary.
The Dump command has two format options.
OPTION 1
Use this option to display the contents of hex 40 bytes (40-column mode) or
hex 80 bytes (80-column mode). For example:
D address
or
D
The contents are dumped starting with the specified address.
If you do not specify an address, the D command assumes the starting address
is the location following the last location displayed by a previous D
command. Thus, it is possible to dump consecutive 40-byte or 80-byte areas
by entering consecutive D commands without parameters.
If no previous D command was entered, the location is offset hex 100 into the
segment originally initialized in the segment registers by DEBUG.
NOTE: If you enter only an offset for the starting address, the D command
assumes the segment contained in the DS register.
OPTION 2
Use this option to display the contents of the specified address range. For
example:
D range
NOTE: If you enter only an offset for the starting address, the D command
assumes the segment contained in the DS register. If you specify an
ending address, enter it with only an offset value.
For example:
D cs:100 10C
A 40-column display format might look like this:
04BA:0100 42 45 52 54 41 20 54 00
BERTA T.
04BA:0108 20 42 4F 52 47
BORG
E (ENTER) COMMAND
PURPOSE
Replaces the contents of one or more bytes, starting at the specified
address, with the values contained in the list (see Option 1).
Displays and allows modification of bytes in a sequential manner (see
Option 2).
FORMAT
E address [list]
PARAMETERS
address Any of the following formats:
A segment register plus an offset, such as CS:0100.
A segment address plus an offset, such as 4BA:0100.
An offset only, such as 100. In this case, the default
segment is used.
list A string of byte values. If you include a character string,
enclose the characters in single or double quotation marks. To
specify a quotation mark as a character within the string when it
is also used to delimit the string, type it twice.
'These ''quotes'' are correct.'
'This one''s okay, too.'
COMMENTS
If you enter only an offset for the address, the E command assumes the
segment contained in the DS register.
The Enter command has two format options.
OPTION 1
Use this option to place the list in memory beginning at the specified
address.
E address list
For example:
E ds:100 F3 'xyz' 8D
Memory locations ds:100 through ds:104 are filled with the 5 bytes specified
in the list.
OPTION 2
Use this option to display the address and the byte of a location, then the
system waits for your input.
For example:
E address
Enter a 1- or 2-character hexadecimal value to replace the contents of the
byte; then take any one of the following actions:
1. Press the space bar to advance to the next address. Its contents are
displayed. If you want to change the contents take option 1, above.
To advance to the next byte without changing the current byte, press the
space bar again.
2. Enter a hyphen to back up to the preceding address. A new line is
displayed with the preceding address and its contents. If you want to
change the contents, take option 1, above.
To back up one more byte without changing the current byte, enter another
hyphen.
3. Press the Enter key to end the Enter command.
NOTE: Display lines can have 4 or 8 bytes of data, depending on whether the
system display format is 40- or 80-column. Spacing beyond an 8-byte
boundary causes a new display line, with the beginning address, to be
started.
For example:
E cs:100
might cause this display:
04BA:0100 EB.
To change the contents of 04BA:0100 from hex EB to hex 41, enter 41.
04BA:0100 EB.41
To see the contents of the next three locations, press the space bar three
times. The screen might look like this:
04BA:0100 EB.41 10. 00. BC.
To change the contents of the current location (04BA:0103) from hex BC to hex
42, enter 42.
04BA:0100 EB.41 10. 00. BC.42
Now, suppose you want to back up and change the hex 10 to hex 6F. This is
what the screen looks like after entering two hyphens and the replacement
byte:
04BA:0100 EB.41 10.00. BC.42-
04BA:0102 00.-
04BA:0101 10.6F
Press the Enter key to end the Enter command. The hyphen prompt will appear.
F (FILL) COMMAND
PURPOSE
Fills the memory locations in the range with the values in the list.
FORMAT
F range list
PARAMETERS
range Either of these two formats:
An address followed by an offset, such as CS:100 110
An address followed by L value, where value is the number of
hexadecimal bytes to be processed. For example, CS:100 L 10.
The limit for range is hexadecimal 10000 or decimal 64K bytes.
To specify a range of 64K bytes within 4 hexadecimal characters,
enter 0000 or 0 for value.
list A string of byte values. If you include a character string,
enclose the characters in single or double quotation marks. To
specify a quotation mark as a character within the string when it
is also used to delimit the string, type it twice.
'These ''quotes'' are correct.'
'This one''s okay, too.'
COMMENTS
If the list contains fewer bytes than the address range, the list is used
repeatedly until all the designated memory locations are filled.
If the list contains more bytes than the address range, the extra list items
are ignored.
NOTE: If you enter only an offset for the starting address of the range, the
Fill command assumes the segment contained in the DS register.
EXAMPLE
F 4BA:100 L 5 F3 'XYZ' 8D
Memory locations 04BA:100 through 04BA:104 are filled with the 5 bytes
specified. Remember that the ASCII values of the list characters are stored.
Thus, locations 100-104 will contain F3 58 59 5A 8D.
G (GO) COMMAND
PURPOSE
Executes the program you are debugging.
Stops the execution when the instruction at a specified address is reached
(breakpoint), and displays the registers, flags, and the next instruction to
be executed.
FORMAT
G [=address] [address [address...]]
PARAMETERS
address Any of the following formats:
A segment register plus an offset, such as CS:0100.
A segment address plus an offset, such as 4BA:0100.
An offset only, such as 100. In this case, the default
segment is used.
COMMENTS
Program execution begins with the current instruction, whose address is
determined by the contents of the CS and IP registers, unless overridden by
the =address parameter (the = must be entered). If =address is specified,
program execution begins with CS:=address.
The Go command has two format options.
OPTION 1
Use this option to execute the program you are debugging without breakpoints.
For example:
G [=address]
This option is useful when testing program execution with different
parameters each time. (Refer to the Name command.) Be certain the CS:IP
values are set properly before issuing the G command, if not using =address.
OPTION 2
This option performs the same function as Option 1 but, in addition, allows
breakpoints to be set at the specified addresses. For example:
G [=address] address
[address...]
This method causes execution to stop at a specified location so the system or
program environment can be examined.
You can specify up to ten breakpoints in any order. You may wish to take
advantage of this if your program has many paths, and you want to stop the
execution no matter which path the program takes.
The DEBUG program replaces the instruction codes at the breakpoint addresses
with an interrupt code (hex CC). If any one breakpoint is reached during
execution, the execution is stopped, the registers and flags are displayed,
and all the breakpoint addresses are restored to their original instruction
codes. If no breakpoint is reached, the instructions are not restored.
NOTES:
1. Once a program has reached completion (DEBUG has displayed the "Program
terminated normally" message), you must reload the program before it can
be executed again.
2. Make sure that the address parameters refer to locations that contain
valid 8086/8088 instruction codes. If you specify an address that does
not contain valid instruction in the first byte, unpredictable results
occur.
3. The stack pointer must be valid and have 6 bytes available for the Go
command, otherwise, unpredictable results occur.
4. If only an offset is entered for a breakpoint, the G command assumes the
segment contained in the CS register.
5. Do not set breakpoints at instructions in read-only memory (ROM BIOS or
ROM BASIC).
For example:
G 102 1EF 208
Be careful not to set a breakpoint between a segment override indication
(such as ES; alone on a line), and the instruction that the override
qualifies.
Execution begins with the current instruction, whose address is the current
values of CS:IP. The =address parameter was not used.
Three breakpoints are specified; assume that the second is reached.
Execution stops before the instruction at location CS:1EF is executed, the
original instruction codes are restored, all three breakpoints are removed,
the display occurs, and the Go command ends.
Refer to the Register command for a description of the display.
H (HEXARITHMETIC) COMMAND
PURPOSE
Adds the two hexadecimal values, then subtracts the second from the first.
Displays the sum and difference on one line.
FORMAT
H value value
EXAMPLE
H 0F 8
0017 0007
The hexadecimal sum of 000F and 0008 is 0017, and their difference is 0007.
I (INPUT) COMMAND
PURPOSE
Inputs and displays (in hexadecimal) 1 byte from the specified port.
FORMAT
I portaddress
PARAMETERS
portaddress A 1-4 character hexadecimal value specifying an 8- or 16-bit port
address.
EXAMPLE
I 2F8
6B
The single hexadecimal byte read from port 02F8 is displayed (6B).
L (LOAD) COMMAND
PURPOSE
Loads a file or absolute disk sectors into memory.
FORMAT
L [address[drive sector sector]]
PARAMETERS
address Any of the following formats:
A segment register plus an offset, such as CS:0100.
A segment address plus an offset, such as 4BA:0100.
An offset only, such as 100. In this case, the default
segment is used.
drive A decimal number that indicates a particular drive. For example,
drive A is 0, drive B is 1, and so on.
sector 1-3 character hexadecimal values that specify the starting
relative sector number and the number of sectors to be loaded or
written.
NOTE: Relative sector numbers are obtained by counting the
sectors on the disk surface. The first sector on the disk
is at track 0, sector 1, head 0, and is relative sector 0.
The numbering continues for each sector on that track and
head, then continues with the first sector on the next
head of the same track. When all sectors on all heads of
the track have been counted, numbering continues with the
first sector on head 0 of the next track.
COMMENTS
The maximum number of sectors that can be loaded with a single Load command
is hex 80. A sector contains 512 bytes.
NOTE: DEBUG displays a message if a disk read error occurs. You can retry
the read operation by pressing the F3 key to re-display the Load
command. Then press the Enter key.
The Load command has two format options.
OPTION 1
Use this option to load data from the disk specified by drive and place the
data in memory beginning at the specified address. For example:
L address drive sector sector
The data is read from the specified starting relative sector (first sector)
and continues until the requested number of sectors is read (second sector).
NOTE: If you only enter an offset for the beginning address, the L command
assumes the segment contained in the CS register.
For example, to load data, you might enter:
L DS:100 1 0F 6D
The data is loaded from the diskette in drive B and placed in memory
beginning at DS:100. Consecutive sectors of data are transferred, 6DH (109),
starting with relative sector hex 0F (15) (the 16th sector on the diskette).
NOTE: Option 1 cannot be used if the drive specified is a network drive.
OPTION 2
When issued without parameters, or with only the address parameter, use this
option to load the file whose file specification is at CS:80. For example:
L
or
L address
This condition is met by specifying the file name when starting the DEBUG
program, or by using the Name command.
NOTE: If DEBUG was started with a file specification and subsequent Name
commands were used, you may need to enter a new Name command for the
proper file specification before issuing the Load command.
The file is loaded into memory beginning at CS:100 (or the location specified
by address), and is read from the drive specified in the file specification,
or from the default drive, if none was specified. Note that files with
extensions of .COM or .EXE are always loaded at CS:100. If you specified an
address, it is ignored.
The BX and CX registers are set to the number of bytes read; however, if the
file being loaded has an extension of .EXE, the BX and CX registers are set
to the actual program size. The file may be loaded at the high end of
memory. Refer to "The DEBUG Work Space" on page 10-3 for the conditions that
are in effect when .EXE or .HEX files are loaded.
For example:
DEBUG
-N myprog
-L
The file named MYPROG is loaded from the default directory and placed in
memory beginning at location CS:0100.
M (MOVE) COMMAND
PURPOSE
Moves the contents of the memory locations specified by range to the
locations beginning at the address specified.
FORMAT
M range address
PARAMETERS
range Either of these two formats:
An address followed by an offset, such as CS:100 110.
An address followed by L value, where value is the number of
hexadecimal bytes to be processed. For example, CS:100 L 10.
The limit for range is hexadecimal 10000 or decimal 64KB. To
specify a range of 64KB within 4 hexadecimal characters, enter
0000 or 0 for value.
address Any of the following formats:
A segment register plus an offset, such as CS:0100.
A segment address plus an offset, such as 4BA:0100.
An offset only, such as 100. In this case, the default
segment is used.
COMMENTS
Overlapping moves are always performed without loss of data during the
transfer. (The source and destination areas share some of the same memory
locations.)
The data in the source area remains unchanged unless overwritten by the move.
NOTES:
1. If you enter only an offset for the beginning address of the range, the M
command assumes the segment contained in the DS register. If you specify
an ending address for the range, enter it with only an offset value.
2. If you enter only an offset for the address of the destination area, the
M command assumes the segment contained in the DS register.
EXAMPLE
M CS:100 L10 500
The 17 bytes of data from CS:100 through CS:110 are moved to the area of
memory beginning at DS:500.
N (NAME) COMMAND
PURPOSE
Formats file control blocks for the first two file specifications, at
CS:5C and CS:6C. (Starting DEBUG with a file specification also formats
a file control block at CS:5C.)
The file control blocks are set up for the Load and Write commands and to
supply required file names for the program being debugged.
All file specifications and other parameters, including delimiters, are
placed exactly as entered in a parameter save area at CS:81, with CS:80
containing the number of characters entered. Register AX is set to
indicate the validity of the drive specifiers entered with the first two
file specifications.
FORMAT
N [d:][path]filename[.ext]
COMMENTS
If you start the DEBUG program without a file specification, you must use the
Name command before a file can be loaded with the L command.
EXAMPLE
DEBUG
-N myprog
-L
To define file specifications or other parameters required by the program
being debugged, enter:
DEBUG myprog
-N file1 file2
In this example, DEBUG loads the file MYPROG at CS:100, and leaves the file
control block at CS:5C formatted with the same file specification. Then, the
Name command formats file control blocks for file1 and file2 at CS:5C and
CS:6C, respectively. The file control block for MYPROG is overwritten. The
parameter area at CS:81 contains all characters entered after the N,
including all delimiters, and CS:80 contains the count of those characters
(hex 0C).
O (OUTPUT) COMMAND
PURPOSE
Sends the byte to the specified output port.
FORMAT
O portaddress byte
PARAMETERS
portaddress A 1-4 character hexadecimal value specifying an 8- or 16-bit port
address.
EXAMPLE
To send the byte value 4F to output port 2F8, enter:
O 2F8 4F
P (PROCEED) COMMAND
PURPOSE
Causes the execution of a subroutine call, a loop instruction, an interrupt,
or a repeat string instruction to stop at the next instruction.
FORMAT
P[=address][value]
PARAMETERS
address Any of the following formats:
A segment register plus an offset, such as CS:0100.
A segment address plus an offset, such as 4BA:0100.
An offset only, such as 100. In this case, the default
segment is used.
value A 1-4 character hexadecimal value, specifying the number of
instructions to execute.
COMMENTS
When at a subroutine call, a loop instruction, an interrupt, or a repeat
string instruction, issue the Proceed command to execute the instruction
(perform the entire function), and return control at the next instruction.
The Proceed command has the same syntax as the Trace command. Specifying P0
is the same as specifying T0.
EXAMPLE
If the following instructions are executed:
0100 CALL 1000
0103 JC 2000
.
.
.
1000 XOR AX,AX
.
.
.
1XXX RET
And if CS:IP was pointing to the CALL 1000 instruction, typing P causes the
execution of the subroutine and returns control to DEBUG at the JC
instruction.
Q (QUIT) COMMAND
PURPOSE
Ends the DEBUG program.
FORMAT
Q
COMMENTS
The file that you are working on in memory is not saved by the Quit command.
You must use the Write command to save the file.
DEBUG returns to the command processor which then issues the normal command
prompt.
EXAMPLE
-Q
A>
R (REGISTER) COMMAND
PURPOSE
The Register command has the following three functions:
Displays the hexadecimal contents of a single register with the option of
changing those contents
Displays the hexadecimal contents of all the registers, plus the
alphabetic flag settings, and the next instruction to be executed
Displays the eight 2-letter alphabetic flag settings with the option of
changing any or all of them.
FORMAT
R [registername]
PARAMETERS
registername The valid names are:
AX SP CS IP
BX BP DS F
CX SI ES
DX DI SS
IP refers to the instruction pointer, and F refers to the flags
register.
COMMENTS
When the DEBUG program starts, the registers and flags are set to certain
values for the program being debugged. (Refer to "The DEBUG Work Space" on
page 10-3.)
DISPLAY A SINGLE REGISTER
To display the contents of a single register, enter the register name:
R AX
The system might respond with:
AX F1E4
:
Now you can take one of two actions: press the Enter key to leave the
contents unchanged, or change the contents of the AX register by entering a
1-4 character hexadecimal value, such as hex FFF.
AX F1E4
:FFF
Now, pressing the Enter key changes the contents of the AX register to hex
0FFF.
DISPLAY ALL REGISTERS AND FLAGS
To display the contents of all registers and flags and the next instruction
to be executed, type:
R
The system responds:
AX=0E00 BX=00FF CX=0007 DX=01FF SP=039D BP=0000 SI=005C DI=0000
DS=3D5B ES=3D5B SS=3D5B CS=3D5B IP=011A NV UP EI PL NZ NA PO NC
3D5B:011A CD21 INT 21
The first four lines display the hexadecimal contents of the registers and
the eight alphabetic flag settings. The last line indicates the location of
the next instruction to be executed and its hexadecimal and unassembled
formats. This is the instruction pointed to by CS:IP.
A system with an 80-column display shows:
1st line - 8 registers
2nd line - 5 registers and 8 flag settings
3rd line - next instruction information
A system with a 40-column display shows:
1st line - 4 registers
2nd line - 4 registers
3rd line - 4 registers
4th line - 1 register and 8 flag settings
5th line - next instruction information
Display All Flags
There are eight flags, each with two-letter codes to indicate either a set
condition or a clear condition. The flags appear in displays in the order
shown in the following table:
+---------------------------------------------------------------------------+
| FLAG NAME SET CLEAR |
+---------------------------------------------------------------------------+
| Overflow (yes/no) OV NV |
+---------------------------------------------------------------------------+
| Direction (decrease/increase) DN UP |
+---------------------------------------------------------------------------+
| Interrupt (enable/disable) EI DI |
+---------------------------------------------------------------------------+
| Sign (negative/positive) NG PL |
+---------------------------------------------------------------------------+
| Zero (yes/no) ZR NZ |
+---------------------------------------------------------------------------+
| Auxiliary carry (yes/no) AC NA |
+---------------------------------------------------------------------------+
| Parity (even/odd) PE PO |
+---------------------------------------------------------------------------+
| Carry (yes/no) CY NC |
+---------------------------------------------------------------------------+
To display all flags, enter:
R F
If all the flags are in a set condition, the response is:
OV DN EI NG ZR AC PE CY -
Now you can either press the Enter key to leave the settings unchanged or
change any or all of the settings.
To change a flag, just enter its opposite code. The opposite codes can be
entered in any order with or without intervening spaces. For example, to
change the first, third, fifth, and seventh flags, enter:
OV DN EI NG ZR AC PE CY - PONZDINV
The changes in this example are entered in reverse order.
Press the Enter key and the flags are modified as specified, the prompt
appears, and you can enter the next command.
If you want to see if the new codes are in effect, enter:
R F
The response is:
NV DN DI NG NZ AC PO CY -
The first, third, fifth, and seventh flags are changed as requested. The
second, fourth, sixth, and eighth flags are unchanged. A single flag can be
changed only once for each R F command.
S (SEARCH) COMMAND
PURPOSE
Searches the range for the character(s) in the list.
FORMAT
S range list
range Either of these two formats:
An address followed by an offset, such as CS:100 110.
An address followed by L value, where value is the number of
hexadecimal bytes to be processed. For example, CS:100 L 10.
The limit for range is hexadecimal 10000 or decimal 64KB. To
specify a range of 64KB within 4 hexadecimal characters, enter
0000 or 0 for value.
list A string of byte values. If you include a character string,
enclose the characters in single or double quotation marks. To
specify a quotation mark as a character within the string when it
is also used to delimit the string, type it twice.
'These ''quotes'' are correct.'
'This one''s okay, too.'
COMMENTS
All matches are indicated by displaying the addresses where matches are
found.
A display of the prompt without an address means that no match was found.
NOTE: If you enter only an offset for the starting address of the range, the
S command assumes the segment contained in the DS register.
EXAMPLE
If you want to search the range of addresses from CS:100 through CS:110 for
hex 41, type:
S CS:100 110 41
If two matches are found the response might be:
04BA:0104
04BA:010D
If you want to search the same range of addresses for a match with the 4-byte
list (41 'AB' E), enter:
S CS:100 L 11 41 'AB' E
The starting addresses of all matches are listed. If no match is found, no
address is displayed.
T (TRACE) COMMAND
PURPOSE
Executes one or more instructions starting with the instruction at CS:IP, or
at =address, if it is specified. The = must be entered. One instruction is
assumed, but you can specify more than one with value. This command displays
the contents of all registers and flags after each instruction executes. For
a description of the display format, refer to the Register command.
FORMAT
T [=address][value]
PARAMETERS
address Any of the following formats:
A segment register plus an offset, such as CS:0100.
A segment address plus an offset, such as 4BA:0100.
An offset only, such as 100. In this case, the default
segment is used.
value A 1-4 character hexadecimal value, specifying the number of
instructions to execute.
COMMENTS
The display caused by the Trace command continues until value instructions
are executed. Therefore, when tracing multiple instructions, remember you
can suspend the scrolling at any time by pressing the Ctrl and the NumLock
keys together, or the Pause key. Resume scrolling by entering any other
character.
NOTES:
1. The Trace command disables all hardware interrupts before executing the
user instruction, and then re-enables the interrupts when the trap
interrupt occurs following the execution of the instruction.
2. TRACE should not be used with any steps that change the contents of the
8259 interrupt mask (ports 20 and 21).
3. If you trace an INT3 instruction, the breakpoint is set at the INT3
location.
EXAMPLE
T
If the IP register contains 011A, and that location contains B40E (MOV
AH,0EH), this may be displayed:
AX=0E00 BX=00FF CX=0007 DX=01FF SP=039D BP=0000 SI=005C DI=0000
DS=3D5B ES=3D5B SS=3D5B CS=3D5B IP=011C NV UP EI PL NZ NA PO NC
3D5B:011C CD21 INT 21
This displays the results after the instruction at 011A is executed, and
indicates the next instruction to be executed is the INT 21 at location
04BA:011C.
T 10
Sixteen instructions are executed (starting at CS:IP). The contents of all
registers and flags are displayed after each instruction. The display stops
after the 16th instruction has been executed. Displays may scroll off the
screen unless you suspend the display by simultaneously pressing the Ctrl and
NumLock keys, or the Pause key.
U (UNASSEMBLE) COMMAND
PURPOSE
Unassembles instructions (that is, translates the contents of memory into
assembler-like statements) and displays their addresses and hexadecimal
values, together with assembler-like statements. For example, a display
might look like this:
04BA:0100 206472 AND [SI+72],AH
04BA:0103 FC CLD
04BA:0104 7665 JBE 016B
FORMAT
U [address]
or
U [range]
PARAMETERS
address Any of the following formats:
A segment register plus an offset, such as CS:0100.
A segment address plus an offset, such as 4BA:0100.
An offset only, such as 100. In this case, the default
segment is used.
range Either of these two formats:
An address followed by an offset, such as CS:100 110.
An address followed by L value, where value is the number of
hexadecimal bytes to be processed. For example, CS:100 L 10.
The limit for range is hexadecimal 10000 or decimal 64KB. To
specify a range of 64KB within 4 hexadecimal characters, enter
0000 or 0 for value.
COMMENTS
The number of bytes to be unassembled depends on your system display format
(40 or 80 columns), and which option you use with the Unassemble command.
NOTES:
1. In all cases, the number of bytes unassembled and displayed may be
slightly more than either the amount requested or the default amount.
This happens because the length of the instructions vary. Therefore,
unassembling the last instruction may result in more bytes than expected.
2. Make sure that the address parameters refer to locations containing valid
8086/8088 instruction codes. If you specify an address that does not
contain the first byte of a valid instruction, the display will be
incorrect.
3. If you enter only an offset for the starting address, the U command
assumes the segment contained in the CS register.
The Unassemble command has the following two format options:
OPTION 1
Use this option to either unassemble instructions without specifying an
address, or to unassemble instructions beginning with a specified address.
For example:
U
or
U address
Sixteen bytes are unassembled with a 40-column display. Thirty-two bytes are
unassembled in 80-column mode.
Instructions are unassembled beginning with the specified address.
If you do not specify an address, the U command assumes the starting address
is the location following the last instruction unassembled by a previous U
command. Thus, it is possible to unassemble consecutive locations, producing
continuous unassembled displays, by entering consecutive U commands without
parameters.
If no previous U command is entered, the location is offset hex 0100 into the
segment originally initialized in the segment registers by DEBUG.
OPTION 2
Use this option to unassemble instructions in a specified address range. For
example:
U range
All instructions in the specified address range are unassembled, regardless
of the system display format.
NOTE: If you specify an ending address, enter it with only an offset value.
For example:
U 04ba:0100 108
The display response may be:
04BA:0100 206472 AND [SI+72],AH
04BA:0103 FC CLD
04BA:0104 7665 JBE 016B
04BA:0106 207370 AND [BP+DI+70],DH
The same display appears if you enter:
U 04BA:100 L 7
or
U 04BA:100 L 8
or
U 04BA:100 L 9
W (WRITE) COMMAND
PURPOSE
Writes the data being debugged to disk.
FORMAT
W [address [drive sector sector]]
PARAMETERS
address Any of the following formats:
A segment register plus an offset, such as CS:0100.
A segment address plus an offset, such as 4BA:0100.
An offset only, such as 100. In this case, the default
segment is used.
drive A decimal number that indicates a particular drive. For example,
drive A is 0, drive B is 1, and so on.
sector 1-3 character hexadecimal values that specify the starting
relative sector number and the number of sectors to be loaded or
written.
NOTE: Relative sector numbers are obtained by counting the
sectors on the disk surface. The first sector on the disk
is at track 0, sector 1, head 0, and is relative sector 0.
The numbering continues for each sector on that track and
head, then continues with the first sector on the next
head of the same track. When all sectors on all heads of
the track have been counted, numbering continues with the
first sector on head 0 of the next track.
COMMENTS
No more than hex 80 sectors can be written with a single Write command. A
sector contains 512 bytes.
DEBUG displays a message if a disk write error occurs. You can retry the
write operation by pressing the F3 key to re-display the Write command, then
press the Enter key.
The Write command has two format options.
OPTION 1
Use this option to write data to disk beginning at a specified address. For
example:
W address drive sector sector
The data beginning at the specified address is written to the disk in the
indicated drive. The data is written starting at the specified starting
relative sector (first sector) and continues until the requested number of
sectors are filled (second sector).
NOTES:
1. Be extremely careful when you write data to absolute sectors because an
erroneous sector specification destroys whatever was on the disk at that
location.
2. If only an offset is entered for the beginning address, the W command
assumes the segment is contained in the CS register.
3. Remember, the starting sector and the sector count are both specified in
hexadecimal.
4. Option 1 cannot be used if the specified drive is a network drive.
For example:
W 1FD 1 100 A
The data beginning at CS:01FD is written to the diskette in drive B, starting
at relative sector hex 100 (256) and continuing for hex 0A (10) sectors.
OPTION 2
This option permits you to use the WRITE command without specifying
parameters or specifying only the address parameter. For example:
W
or
W address
When issued as shown above, the Write command writes the file (whose file
specification is at CS:80) to disk.
This condition is met by specifying the file when starting the DEBUG program,
or by using the Name command.
NOTE: If DEBUG was started with a file specification and subsequent Name
commands were used, you may need to enter a new Name command for the
proper file specification before issuing the Write command.
In addition, the BX and CX registers must be set to the number of bytes to be
written. They may have been set properly by the DEBUG or Load commands, but
were changed by a Go or Trace command. You must be certain the BX and CX
registers contain the correct values.
The file beginning at CS:100, or at the location specified by address, is
written to the diskette in the drive included in the file specification or
the default drive if no drive was specified.
The debugged file is written over the original file that was loaded into
memory, or into a new file if the file name in the FCB didn't previously
exist.
NOTE: An error message is issued if you try to write a file with an
extension of .EXE or .HEX. These files are written in a specific
format that DEBUG cannot support.
If you find it necessary to modify a file with an extension of .EXE or .HEX,
and the exact locations to be modified are known, use the following
procedure:
1. RENAME the file to an extension other than .EXE or .HEX.
2. Load the file into memory using the DEBUG or Load command.
3. Modify the file as needed in memory, but do not try to execute it with
the Go or Trace commands. Unpredictable results would occur.
4. Write the file back using the Write command.
5. RENAME the file to its correct name.
XA (EMS ALLOCATE) COMMAND
PURPOSE
Allocates a specified number of expanded memory pages to a handle.
FORMAT
XA count
COMMENTS
The count indicates the number of 16K pages to allocate. If the amount of
expanded memory identified by count is available, a message is displayed,
indicating that a handle has been created. The XS (EMS Status) command can
be used to display the number of expanded memory pages that are available.
EXAMPLE
To allocate two EMS pages, enter:
XA 2
If two pages of memory are available, a message like this is displayed:
Handle created = 000E
XD (EMS DEALLOCATE) COMMAND
PURPOSE
Deallocates a handle.
FORMAT
XD handle
COMMENTS
The handle identifies the number of the handle to be deallocated. If the
number is valid, a message is displayed, indicating the handle has been
deallocated. The XS (EMS Status) command can be used to display the handles
currently being used.
EXAMPLE
To deallocate a handle when you have only one allocated, you can enter:
XD 000E
If the handle deallocation is successful, you receive a message like this:
Handle 000E deallocated.
XM (EMS MAP) COMMAND
PURPOSE
Maps an EMS logical page to an EMS physical page from an EMS handle.
FORMAT
XM lpage ppage handle
COMMENTS
The lpage specifies the number of the handle's logical page that is to be
mapped. The ppage is the number of the physical page to be mapped to. The
handle is the EMS allocated label used to reference a group of logical pages.
If syntax items are valid, a message is displayed indicating that the logical
page has been mapped to the physical page.
EXAMPLE
To map a logical page to a physical page using handle 0001, you can enter:
XM 1 0 1
If the mapping is successful, you receive this message:
Logical page 01 mapped to physical page 00.
XS (EMS STATUS) COMMAND
PURPOSE
Displays the status of expanded memory.
FORMAT
XS
COMMENTS
The following expanded memory information is displayed:
Handle %1 has %2 pages allocated
.
.
.
Physical page %1 = Frame segment %2
.
.
.
%1 of a total %2 EMS pages have been allocated
%1 of a total %2 EMS handles have been allocated
EXAMPLE
A line is displayed for each handle allocated with its associated logical
page count.
DEBUG ERROR MESSAGES
The following error messages are produced by the DEBUG utility:
ACCESS DENIED The result of attempting to Write (W) to a
read-only file.
DISK ERROR READING DRIVE %1 An invalid parameter was entered on the
Load (L) command or an error occurred on
issuing the Load (L) command.
DISK ERROR WRITING DRIVE %1 An invalid parameter was entered on the
Write (W) command or an error occurred on
issuing the Write (W) command.
EMS HARDWARE/SOFTWARE FAILURE The result of an EMS command. Tells the
user EMS is not functioning properly.
EMS NOT INSTALLED The result of an EMS command. Tells user
EMS is not installed.
&HAT. ERROR Points to the offending operand in an error
condition.
ERROR IN EXE OR HEX FILE The EXE or HEX file are in error.
EXE AND HEX FILES CANNOT BE WRITTEN A file in EXE or HEX format cannot be
written to a disk.
EXEC FAILURE The execution of the requested file failed.
FILE CREATION ERROR The result of attempting to Write (W) to a
system or hidden file.
FILE NOT FOUND Issued from the Load (L) command when a
file is not found for loading.
FREE PAGES EXCEEDED The result of an EMS command. Tells the
user that the request has exceeded the
amount of free EMS pages available.
HANDLE NOT FOUND The result of an EMS command. Tells the
user an EMS handle was not found.
INCORRECT DOS VERSION Incorrect version of DEBUG for the DOS
version running.
INSUFFICIENT MEMORY Not enough memory to Load (L) the specified
file.
INSUFFICIENT SPACE ON DISK Out of disk space for a Write (W) command.
INVALID DRIVE SPECIFICATION The drive referenced by the Name (N) and
Load (L) command is invalid; that is, it
does not exist.
LOGICAL PAGE OUT OF RANGE The result of an EMS command. Tells the
user that the logical page requested is not
in the range of possible pages.
MISSING OR INVALID EMS PARAMETER The result of an EMS command. Tells the
user a missing or invalid parameter was
entered.
NO FREE HANDLES The result of an EMS command. Tells the
user that there are no more EMS handles
available for allocation.
PARAMETER ERROR The result of an EMS command. Tells the
user that an EMS parameter is in error.
PHYSICAL PAGE OUT OF RANGE The result of an EMS command. Tells the
user that the physical page requested is
not in the range of possible pages.
PROGRAM TERMINATED NORMALLY An Interrupt 20H has been encountered,
signalling program termination.
TOTAL PAGES EXCEEDED The result of an EMS command. Tells the
user that the total EMS pages have been
exceeded.
WRITE (W) ERROR, NO DESTINATION DEFINED Attempt to Write (W) to a file that
has not yet been Named (N).
WRITE PROTECT ERROR WRITING DRIVE %1 A Write (W) to a write-protected disk
caused an error.
WRITING %1 BYTES Reports the number of bytes written to a
file when the Write (W) command is issued.
Chapter 11
CHAPTER 11. WRITING AN INSTALLABLE DEVICE DRIVER 26
Types of Device Drivers 39
Character Device Drivers 48
Block Device Drivers 55
How DOS 4.00 Installs Device Drivers 84
The Basic Parts of a Device Driver 134
The Device Driver Header 148
The Strategy Routine 274
The Interrupt Routines 283
How DOS 4.00 Passes a Request 300
Responding to Requests 392
Initialization Request 456
Media Check Request 511
Build BPB Request 630
Input and Output Requests 815
Nondestructive Input No Wait Request 879
Character Input and Output Status Requests 901
Character Input and Output Flush Requests 935
Open and Close Requests 951
Removable Media Request 983
Generic IOCTL Request 1008
Get Logical Device Request 1037
Set Logical Device Request 1055
CLOCK$ Device Driver Example 1073
CHAPTER 11. WRITING AN INSTALLABLE DEVICE DRIVER
This chapter provides guide and system architecture information to support
successful creation of an installable device driver.
We recommend you use the information provided in this chapter in conjunction
with the information provided in the VDISK.ASM file on the utilities
diskette. This file contains the fully documented source code for the VDISK
device driver, which emulates a fixed disk in RAM.
NOTE: The example on the utilities diskette does not reflect the current
level of VDISK.SYS..
TYPES OF DEVICE DRIVERS
A device driver is a memory image file or an .EXE file that contains the code
needed to implement a device. DOS 4.00 allows two types of device drivers to
be installed:
Character device drivers
Block device drivers.
CHARACTER DEVICE DRIVERS
Character device drivers perform character I/O in a serial manner and have
names such as CON, AUX, CLOCK$. You can open handles or FCBs to perform
input and output to character devices. Because character device drivers have
only one name, they support only one device.
BLOCK DEVICE DRIVERS
Block device drivers are the fixed disk or diskette drives on the system.
They perform random I/O in pieces called blocks, which are usually the
physical sector size of the disk. Block devices are not named as character
devices are and you cannot open them. Instead they are mapped using the
drive letters such as A, B, and C.
A single block device driver can be responsible for one or more disk or
diskette drives. For example, the first block device driver in the device
chain may define four units such as A, B, C, and D. The second device driver
may define three units: E, F, and G. The limit is 26 devices with the
letters A through Z assigned to drives. The position of the driver in the
chain determines the way in which the drive units and drive letters
correspond.
Support for Media Greater than 32MB
A block device driver that runs in the DOS 4.00 environment can be written to
process 32-bit sector numbers. This ability provides support for fixed disk
media greater than 32MB. This support is described in these sections:
"The Device Driver Header" on page 11-3
"Build BPB Request" on page 11-14
"Input and Output Requests" on page 11-18.
DOS 4.00 also allows users to install their own device drivers that support
media greater than 32MB.
HOW DOS 4.00 INSTALLS DEVICE DRIVERS
DOS 4.00 installs device drivers dynamically at startup time by reading and
processing the DEVICE command in CONFIG.SYS. For example, if you have
written a device driver called DRIVER1, include the following command in
CONFIG.SYS:
device=driver1
The DOS 4.00 device interface links device drivers together in a chain,
permitting you to add device drivers for optional devices.
Each device must be initialized. The device driver's initialization
interrupt routine is called once when the device is installed. The
initialization routine returns the location in memory of the ending address
of the device driver. After setting the ending address field, a character
device driver sets the status word and returns.
DOS 4.00 processes installed character device drivers before handling default
devices. To have DOS 4.00 install a new CON device (for example, in the
device driver header's Name/Unit field) name the device CON and set the
standard input device and standard output device bits in the attribute field.
Because DOS 4.00 installs drivers anywhere in memory, care must be taken in
any references to locations not in the segment. Your driver will not always
be loaded at the same memory location each time.
Block devices are installed in the same manner as character devices, above.
Block devices return additional information such as the number of units.
This number identifies the devices' logical names. For example, if the
current maximum logical device letter is F at the time of the install call,
and the block device driver initialization routine returns three logical
units, the logical names of the devices are G, H, and I. The mapping is
determined by the position of the driver in the device list and the number of
units associated with the device. The number of units returned by INIT
overrides the value in the name/unit field of the device header.
A block device also returns a pointer to a BIOS parameter block (BPB) array.
This is a pointer to an array of n word pointers, where n is the number of
units defined. If all the units are the same, the array is able to point to
the same BIOS parameter block, thus saving space. The array must be
protected below the ending address pointer set by the return.
The BPB contains information pertinent to the devices such as the sector size
and the number of sectors per allocation unit. The sector size in the BPB
cannot be greater than the maximum allowed size set by DOS 4.00
initialization.
A block device returns the media descriptor byte passed to devices to report
which parameters DOS 4.00 is using for a particular drive unit.
THE BASIC PARTS OF A DEVICE DRIVER
A device driver is a memory image file or an .EXE file containing the code
needed to implement a device. All DOS 4.00 installable device drivers have
these things in common:
A device driver header, which identifies the device to DOS 4.00 and
defines the strategy and interrupt entry points. Since a device driver
is simply loaded and does not use a program segment prefix, the device
header must be located at physical location 0 of the device driver (ORG 0
or no ORG statement).
A strategy routine, which saves a pointer to the Request Header.
The interrupt routines, which perform the requested operation.
THE DEVICE DRIVER HEADER
A device driver requires a device header containing the following:
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Pointer to next device header DWORD |
+---------------------------------------------------------------------------+
| Attribute WORD |
+---------------------------------------------------------------------------+
| Pointer to device strategy routine WORD |
+---------------------------------------------------------------------------+
| Pointer to device interrupt routine WORD |
+---------------------------------------------------------------------------+
| Name/unit field 8 BYTES |
+---------------------------------------------------------------------------+
Pointer to Next Device Header
The device driver header is a pointer to the device header of the next device
driver. It is a doubleword field set by DOS 4.00 at the time the device
driver is loaded. The first word is an offset and the second word is the
segment.
If you are loading only one device driver, set the device header field to -1
before loading the device. If you are loading more than one device driver,
set the first word of the device header field to the offset of the next
device driver's header. Set the device header field of the last device
driver to -1.
Attribute Field
The attribute field identifies the device to DOS 4.00.
Bit 15
Bit 15 identifies whether the device is a block device or a character device.
If bit 15 is set to 0, this indicates a block device. Setting bit 15 to 1
indicates a character device. Note how the setting of bit 15 affects the
interpretation of the setting of the bits below.
Bit 14
Bit 14, for both character and block devices, tells DOS 4.00 whether the
device driver can handle control strings through IOCtl 44H, AL=2 through
AL=5. Set bit 14 to 1 if control strings can be processed. IOCtl
subfunctions permit the device driver to interpret the information passed to
it, such as setting a baud rate or changing form lengths, without performing
standard reads and writes. Set bit 14 to 0 if control strings cannot be
processed. DOS 4.00 will return an error if an IOCtl is issued to send or
receive control strings and bit 14 is set to 0.
Bit 13
Bit 13 is used for both block and character devices. For block devices, set
bit 13 to 0 if the media is an IBM format. Set bit 13 to 1 if the media is a
non-IBM format. For character devices, set bit 13 to 0 if the driver
supports output-until-busy. Set bit 13 to 1 if it does not.
With the support of output-until-busy, the device driver will send characters
to the device if the device is ready. If the device is not ready, the device
driver will immediately return an error.
Bit 12
Bit 12 is reserved.
Bit 11
Set bit 11 if the device driver can handle removable media. This bit is
called the open/close removable media bit.
Bits 10 through 7
Bits 10 through 7 are reserved.
Bit 6
Bit 6 is the generic IOCtl bit for both character and block device drivers.
If this bit is set to 1, the device driver supports generic IOCtl function
calls. Setting this bit to 1 also indicates support of the Get/Set Logical
Drive function for a block device driver.
Bits 5 and 4
Bits 5 and 4 are reserved.
Bit 3
Set bit 3 to 1 if the character device is a clock device; set bit 3 to 0 if
it is not.
Bit 2
Set bit 2 to 1 if the character device is the NUL device; set bit 2 to 0 if
it is not. Setting the bit tells DOS 4.00 whether the NUL device is being
used. The NUL device cannot be reassigned.
Bit 1
If bit 15 is set to 0 for a character device, set bit 1 to 1 to indicate that
the character device is the current standard output device. If bit 15 is set
to 1 for a block device, set bit 1 to 1 to indicate support for 32-bit sector
numbers; otherwise 16-bit sector number support is assumed.
Bit 0
Set bit 0 to 1 if the character device is the current standard input device;
set bit 0 to 0 if it is not the current standard input device.
Pointers to Strategy Routine and Interrupt Routines
When DOS 4.00 passes a request to a device driver, it calls the device driver
twice. These two fields point to the first and second entry points: the
strategy routine and the interrupt routine. The fields are word values, so
they must be in the same segment as the device header.
Name/Unit Field
These 8-byte fields identify a character device by name or a block device by
unit. A character device name is left-justified followed by spaces, if
necessary. For block devices, although DOS 4.00 automatically fills in this
field with the value of number of units returned by INIT call, you may choose
to place the number of units in the first place.
THE STRATEGY ROUTINE
DOS 4.00 calls a device driver at the strategy routine at first, passing in a
request packet the information describing what DOS 4.00 wants the device
driver to do.
The strategy routine does not perform the request but queues the request or
saves a pointer to the request packet.
THE INTERRUPT ROUTINES
DOS 4.00 calls the device driver's interrupt routine with no parameters
immediately after the strategy routine returns. An interrupt routine's
function is to perform the operation based on the queued request, process any
data in the request packet, and set up information being returned to DOS
4.00.
It is the responsibility of the device driver to preserve the system state.
For example, the device driver must save all registers on entry and restore
them on exit. The stack maintained by DOS 4.00 is used to save all
registers. If more stack space is needed, it is the device driver's
responsibility to allocate and maintain an additional stack.
All calls to device drivers are FAR calls. FAR returns should be executed to
return to DOS 4.00.
HOW DOS 4.00 PASSES A REQUEST
DOS 4.00 passes a pointer in ES:BX to the request packet. The packet
consists of a request header that contains information common to all
requests, followed by data pertinent to the request being made.
The structure of the request header is shown below.
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Length of the request header and subsequent data BYTE |
+---------------------------------------------------------------------------+
| Unit code for block devices only BYTE |
+---------------------------------------------------------------------------+
| Command code BYTE |
+---------------------------------------------------------------------------+
| Status WORD |
+---------------------------------------------------------------------------+
| Reserved 8-BYTE |
+---------------------------------------------------------------------------+
| Data VARIABLE |
+---------------------------------------------------------------------------+
Length Field
The length field identifies the length of the request header and subsequent
data in bytes.
Unit Code Field
The unit code field identifies the requesting unit in a block device driver.
If a block device driver has three units defined, for example, the possible
values for the unit code field are 0, 1, or 2.
Command Code Field
The command code identifies the request. See "Responding to Requests" on
page 11-8 for a list of command code values and request descriptions.
Status Field
The status word field is zero on entry and is set by the driver interrupt
routine on return.
Bit 15
Bit 15 is the error bit. If bit 15 is set to 1, the low order 8 bits of the
status word (7-0) indicate the error code.
Bits 14 - 10
Bits 14 through 10 are reserved.
Bit 9
Bit 9 is the busy bit. As a response to status request call, character
device drivers can set the busy bit to indicate whether or not a device is
ready to perform input and output requests. Block device drivers can set the
busy bit to indicate removable or nonremovable media. See "Character Input
and Output Status Requests" on page 11-21 and "Removable Media Request" on
page 11-23 for more information about the calls.
Bit 8
Bit 8 is the done bit. If set, the operation is complete. The driver sets
the done bit to 1 when it exits.
Bits 7 - 0
Bits 7 through 0 are the low order 8 bits of the status word. If bit 15 is
set, bits 7 through 0 contain the error codes. The error codes and errors
are:
CODES MEANING
00 Write protect violation
01 Unknown unit
02 Device not ready
03 Unknown command
04 CRC error
05 Bad drive request structure length
06 Seek error
07 Unknown media
08 Sector not found
09 Printer out of paper
0A Write fault
0B Read fault
0C General failure
0D Reserved
0E Reserved
0F Invalid disk change
RESPONDING TO REQUESTS
Each request packet that is passed to the device driver contains a command
code value in the request header to tell the driver which function to
perform. The table below contains the DOS 4.00 device interface command code
values and the functions to be performed when these values are passed with
data. Note that some of these functions are specific to either a block
device or a character device.
Following this table are detailed descriptions of request data structures and
what the interrupt routines are expected to do. Some of these descriptions
pertain to more than one command code.
+---------------------------------------------------------------------------+
| COMMAND REQUEST DEVICE |
| CODE DESCRIPTION TYPE |
+---------------------------------------------------------------------------+
| 0 Initialization Both |
+---------------------------------------------------------------------------+
| 1 Media check Block |
+---------------------------------------------------------------------------+
| 2 Build BPB Block |
+---------------------------------------------------------------------------+
| 3 IOCtl input (called only if bit 14 of attribute is Both |
| set to 1) |
+---------------------------------------------------------------------------+
| 4 Input (read) Both |
+---------------------------------------------------------------------------+
| 5 Nondestructive input no wait Character |
+---------------------------------------------------------------------------+
| 6 Input status Character |
+---------------------------------------------------------------------------+
| 7 Input flush Character |
+---------------------------------------------------------------------------+
| 8 Output (write) Both |
+---------------------------------------------------------------------------+
| 9 Output (write with verify) Block |
+---------------------------------------------------------------------------+
| 10 Output status Character |
+---------------------------------------------------------------------------+
| 11 Output flush Character |
+---------------------------------------------------------------------------+
| 12 IOCtl output (called only if bit 14 of attribute is Both |
| set to 1 |
+---------------------------------------------------------------------------+
| 13 Device open (called only if bit 11 of attribute is Both |
| set to 1) |
+---------------------------------------------------------------------------+
| 14 Device close (called only if bit 11 of attribute is Both |
| set to 1) |
+---------------------------------------------------------------------------+
| 15 Removable media (called only if bit 11 of attribute Block |
| is set to 1) |
+---------------------------------------------------------------------------+
| 19 Generic IOCtl Request (called Both |
| only if bit 6 of attribute is set to 1) |
+---------------------------------------------------------------------------+
| 23 Get logical device (called only if bit 6 of Block |
| attribute is set to 1) |
+---------------------------------------------------------------------------+
| 24 Set logical device (called only if bit 6 of Block |
| attribute is set to 1) |
+---------------------------------------------------------------------------+
INITIALIZATION REQUEST
COMMAND CODE = 0
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Request header 13-BYTE |
+---------------------------------------------------------------------------+
| Number of units (not set by character devices) BYTE |
+---------------------------------------------------------------------------+
| Ending address of resident program code DWORD |
+---------------------------------------------------------------------------+
| Pointer to BPB array (not set by character devices) pointer DWORD |
| to remainder of arguments |
+---------------------------------------------------------------------------+
| Drive number BYTE |
+---------------------------------------------------------------------------+
| CONFIG.SYS Error Message control flag WORD |
+---------------------------------------------------------------------------+
The driver must do the following:
Set the number of units (block devices only).
Set up the pointer to the BPB array (block devices only).
Perform any initialization code (to modems, printers, and others).
Set the ending address of the resident program code.
Set the status word in the request header.
To obtain information passed from CONFIG.SYS to a device driver at
initialization time, the BPB pointer field points to a buffer containing the
information passed in CONFIG.SYS following the =. This string may end with
either a carriage return (0DH) or a linefeed (0AH). This information is
read-only. Only system calls 01H-0CH and 30H can be issued by the
initialization code of the driver.
The last byte parameter contains the drive letter for the first unit of a
block driver. For example, 0=A, 1=B and so forth.
If an initialization routine determines that it cannot set up the device and
wants to terminate without using any memory, use the following procedure:
Set the number of units to 0.
Set the ending address offset to 0.
Set the ending address segment to the code segment (CS).
If there are multiple device drivers in a single memory image file, the
ending address returned by the last initialization called is the one DOS 4.00
uses. IBM recommends that all device drivers in a single memory image file
return the same ending address.
If initialization of your device driver fails, and you want the system to
display the ERROR IN CONFIG.SYS LINE # error message, set the CONFIG.SYS
error message control flag to a non-zero value.
MEDIA CHECK REQUEST
COMMAND CODE = 1
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Request header 13-BYTE |
+---------------------------------------------------------------------------+
| Media descriptor from DOS 4.00 BYTE |
+---------------------------------------------------------------------------+
| Return BYTE |
+---------------------------------------------------------------------------+
| A pointer to the previous volume ID (if bit 11 = 1 and disk DWORD |
| change is returned) |
+---------------------------------------------------------------------------+
When the command code field is 1, DOS 4.00 calls Media Check for a drive unit
and passes its current Media Descriptor byte. See "Media Descriptor Byte."
Media Check returns one of the following:
Media not changed
Media changed
Not sure
Error code.
The driver must perform the following:
Set the status word in the request header.
Set the return byte to:
-1 for "media changed"
0 for "not sure"
1 for "media not changed."
The driver uses the following method to determine how to set the return byte:
If the media is nonremovable (a fixed disk), set the return byte to 1.
If less than 2 seconds since last successful access, set the return byte
to 1.
If changeline not available, set the return byte to 0.
If changeline is available but not active, set the return byte to 1.
If the media byte in the new BPB does not match the old media byte, set
the return byte to -1.
If the current volume ID matches the previous volume ID, or if the serial
number matches the previous serial number, set the return byte to 0.
Media Descriptor Byte
Currently the media descriptor byte has been defined for some media types.
This byte should be identical to the media byte if the device has the non-IBM
format bit off. These predefined values are:
Media descriptor
byte --> 1 1 1 1 1 x x x
bits --> 7 6 5 4 3 2 1 0
BIT MEANING
0 1=2-sided 0=not 2-sided
1 1=8 sector 0=not 8 sector
2 1=removable 0=not removable
3-7 must be set to 1
NOTE: An exception to the above is that the media descriptor byte value of
F0, which is used to indicate any media types not defined, and F9,
which is used for 5.25-inch media with 2 sides and 15 sectors/tracks.
Examples of current DOS 4.00 media descriptor bytes:
+---------------------------------------------------------------------------+
| DISK # SECTORS/ MEDIA |
| TYPE SIDES TRACK DESCRIPTOR |
+---------------------------------------------------------------------------+
| Fixed disk -- -- F8H |
+---------------------------------------------------------------------------+
| 5.25 inch 2 15 F9H |
+---------------------------------------------------------------------------+
| 5.25 inch 1 9 FCH |
+---------------------------------------------------------------------------+
| 5.25 inch 2 9 FDH |
+---------------------------------------------------------------------------+
| 5.25 inch 1 8 FEH |
+---------------------------------------------------------------------------+
| 5.25 inch 2 8 FFH |
+---------------------------------------------------------------------------+
| 8 inch 1 26 FEH |
+---------------------------------------------------------------------------+
| 8 inch 2 26 FDH |
+---------------------------------------------------------------------------+
| 8 inch 2 8 FEH |
+---------------------------------------------------------------------------+
| 3.5 inch 2 9 F9H |
+---------------------------------------------------------------------------+
| 3.5 inch 2 18 F0H |
+---------------------------------------------------------------------------+
To determine whether you are using a single-sided or a double-sided diskette,
attempt to read the second side. If an error occurs, you may assume the
diskette is single-sided. Media descriptor F0H may be used for those media
types not described earlier. Programs should not use the media descriptor
values to distinguish media. DOS 4.00 internal routines use information in
the BIOS parameter block (BPB) to determine the media type of IBM-formatted
diskettes. These media descriptor bytes do not necessarily indicate a unique
media type.
For 8-inch diskettes:
FEH (IBM 3740 Format) -- Single-sided, single-density, 128 bytes per
sector, soft-sectored, 4 sectors per allocation unit, 1 reserved sector,
2 FATs, 68 directory entries, 77*26 sectors.
FDH (IBM 3740 Format) -- Double-sided, single-density, 128 bytes per
sector, soft-sectored, 4 sectors per allocation unit, 4 reserved sectors,
2 FATs, 68 directory entries, 77*26*2 sectors.
FEH -- Double-sided, double-density, 1024 bytes per sector, soft
sectored, 1 sector per allocation unit, 1 reserved sector, 2 FATs, 192
directory entries, 77*8*2 sectors.
BUILD BPB REQUEST
COMMAND CODE = 2
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Request header 13-BYTE |
+---------------------------------------------------------------------------+
| Media descriptor from DOS 4.00 BYTE |
+---------------------------------------------------------------------------+
| Transfer address (buffer address) DWORD |
+---------------------------------------------------------------------------+
| Pointer to BPB table DWORD |
+---------------------------------------------------------------------------+
DOS 4.00 calls Build BPB (BIOS Parameter Block) under the following two
conditions:
If "Media Changed" is returned
If "Not Sure" is returned, there are no used buffers. Used buffers are
buffers with changed data not yet written to the disk.
The driver must do the following:
Set the pointer to the BPB
Set the status word in the request header.
The device driver must determine the media type that is in the unit to return
the pointer to the BPB table. In previous versions of IBMBIO, the FAT ID
byte determined the structure and layout of the media. The FAT ID byte has
only eight possible values (F8 through FF), so, as new media types are
invented, the available values will soon be exhausted. With the varying
media layouts, DOS 4.00 needs to be aware of the location of the FATs and
directories before it asks to read them.
The following paragraphs explain the method DOS 4.00 uses to determine the
media type.
The information relating to the BPB for a particular media is kept in the
boot sector for the media. The format of the boot sector is as follows:
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| A 2-byte short JMP instruction (EBH), followed by a NOP WORD |
| instruction (90H). |
+---------------------------------------------------------------------------+
| Product name and version 8 BYTES |
+---------------------------------------------------------------------------+
| Bytes per sector; must be power of 2 WORD |
+---------------------------------------------------------------------------+
| Sectors per allocation unit; must be power of 2 BYTE |
+---------------------------------------------------------------------------+
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Reserved sectors starting at logical sector 0 WORD |
+---------------------------------------------------------------------------+
| Number of FATs BYTE |
+---------------------------------------------------------------------------+
| Maximum number of root directory entries WORD |
+---------------------------------------------------------------------------+
| Total number of sectors in media including the boot sector, WORD |
| FAT areas, and directories |
+---------------------------------------------------------------------------+
| Media descriptor BYTE |
+---------------------------------------------------------------------------+
| Number of sectors occupied by a FAT WORD |
+---------------------------------------------------------------------------+
| Sectors per track WORD |
+---------------------------------------------------------------------------+
| Number of heads WORD |
+---------------------------------------------------------------------------+
| Number of hidden sectors WORD |
+---------------------------------------------------------------------------+
The BPB information contained in the boot sector starts with the Bytes per
Sector entry. The last three words are intended to help the device driver
identify the media. The number of heads is useful for supporting different
multihead drives with the same storage capacity but a different number of
surfaces. The number of hidden sectors is useful for supporting drive
partitioning schemes.
For drivers that support volume identification and disk change, this call
causes a new volume identification to be read from the disk. This call
indicates that the disk has changed in a permissible manner.
To handle the partition that is bigger than 32MB, or one that starts beyond
or crosses the 32MB boundary, DOS 4.00 defines an extended BPB structure.
Depending on the size of the media, you can use either the existing BPB or
the extended one, which contains an additional DWORD field to indicate the
size of the partition in sectors.
Bit 1 of the attribute field in the block device driver header indicates
whether the device can process 32-bit sector numbers. Set bit 1 to indicate
32-bit support.
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Bytes per sector WORD |
+---------------------------------------------------------------------------+
| Sectors per allocation unit BYTE |
+---------------------------------------------------------------------------+
| Reserved sectors starting at logical sector 0 WORD |
+---------------------------------------------------------------------------+
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Number of FATs -- 0 if not a FAT system BYTE |
+---------------------------------------------------------------------------+
| Maximum number of root directory entries WORD |
+---------------------------------------------------------------------------+
| Total number of sectors in the media. This field is used to WORD |
| define a partition that is less than 32MB. Setting this |
| field to 0 indicates to use the total (32-bit) number of |
| sectors in the media below. |
+---------------------------------------------------------------------------+
| Media descriptor BYTE |
+---------------------------------------------------------------------------+
| Number of sectors occupied by a FAT WORD |
+---------------------------------------------------------------------------+
| Sectors per track WORD |
+---------------------------------------------------------------------------+
| Number of heads WORD |
+---------------------------------------------------------------------------+
| Number of hidden sectors DWORD |
+---------------------------------------------------------------------------+
| Total (32-bit) number of sectors in the media. This field is DWORD |
| used to define a partition that is greater than 32MB, or one |
| that crosses the 32MB boundary. |
+---------------------------------------------------------------------------+
The extended BPB is a superset of the traditional BPB structure. To achieve
the maximum compatibility between this structure and that of the traditional
BPB, DOS 4.00 uses the following rule:
If (the number of hidden sectors plus the total number of sectors in the
media) is greater than 64KB, use the 32-bit total number of sectors in
the media entry (DWORD).
Otherwise, use the TOTAL NUMBER OF SECTORS IN THE MEDIA entry (WORD).
A boot record exists at the beginning of each disk partition and each
extended DOS 4.00 partition volume. DOS 4.00 automatically creates the
extended boot record. The format of the extended boot record is:
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| A 2-byte short JMP instruction (EBH) followed by a NOP WORD |
| instruction (90H). |
+---------------------------------------------------------------------------+
| Product name and version 8 BYTES |
+---------------------------------------------------------------------------+
| Extended BPB 25 BYTES |
+---------------------------------------------------------------------------+
| Physical drive number BYTE |
+---------------------------------------------------------------------------+
| Reserved BYTE |
+---------------------------------------------------------------------------+
| Extended boot record signature BYTE |
+---------------------------------------------------------------------------+
| Volume serial number DWORD |
+---------------------------------------------------------------------------+
| Volume label 11 BYTES |
+---------------------------------------------------------------------------+
| Reserved 8 BYTES |
+---------------------------------------------------------------------------+
NOTE: The value of Extended boot record signature is 29H. The value of the
physical drive number is always 0H or 80H.
On all requests to extended drivers with a sector number in their request
headers, the sector number is a DWORD. The standard DOS 4.00 block device
drivers set the attribute bit 1 for 32-bit support.
For each call to a device driver, DOS 4.00 checks to see if the starting
sector number passed in the request can be supported by the device driver.
If this value is greater than 64K for an old-style device driver, DOS 4.00
returns an UNKNOWN MEDIA (07H) device driver error.
INPUT AND OUTPUT REQUESTS
COMMAND CODES = 3, 4, 8, 9, 12
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Request header 13-BYTE |
+---------------------------------------------------------------------------+
| Media descriptor byte BYTE |
+---------------------------------------------------------------------------+
| Transfer address (buffer address) DWORD |
+---------------------------------------------------------------------------+
| Byte/sector count WORD |
+---------------------------------------------------------------------------+
| Starting sector number (If -1, use DWORD starting sector WORD |
| number. This entry has no meaning for a character device.) |
+---------------------------------------------------------------------------+
| For DOS 3.0 to DOS 4.00, pointer to the volume identification DWORD |
| if error code 0FH is returned |
+---------------------------------------------------------------------------+
| Starting 32-bit sector number. (Use this entry to the block DWORD |
| device driver with the attribute bit 1 set.) |
+---------------------------------------------------------------------------+
The DOS 4.00 INPUT/OUTPUT request structure can process 32-bit sector
numbers, providing support for media of more than 4 billion sectors.
The driver must do the following:
Set the status word in the request header
Perform the requested function
Set the actual number of sectors or bytes transferred.
No error checking is performed on an IOCtl call. However, the driver must
set the return sector or byte count to the actual number of bytes
transferred.
Under certain circumstances the block device driver may be asked to do a
WRITE operation of 64KB that seems to be a wraparound of the transfer address
in the device driver request packet. This occurs because an optimization is
added to the WRITE code in DOS 4.00. It will only happen on WRITEs that are
within a sector size of 64KB on files that are being extended past the
current end of file. The block device driver is allowed to ignore the
balance of the WRITE that wraps around. For example, a WRITE of 10000H bytes
of sectors with a transfer address of XXXX:1 ignores the last two bytes.
Remember that a program using DOS 4.00 function calls cannot request an input
or output operation of more than FFFFH bytes because a wrap around in the
transfer buffer segment must occur. You can ignore bytes that would have
wrapped around in the transfer segment.
If the driver returns an error code of 0FH (Invalid Disk Change), it must
provide a DWORD pointer to an ASCIIZ string identifying the correct volume ID
and the system prompts the user to reinsert the disk.
The reference count of open files on the disk maintained by OPEN and CLOSE
calls allows the driver to determine when to return error 0FH. If there are
no open files (reference count=0) and the disk has been changed, the I/O is
valid, and error 0FH is not returned. If there are open files (reference
count > 0) and the disk has been changed, an error 0FH situation may exist.
DOS 4.00 IBMDOS.COM will request an OPEN or CLOSE function only if SHARE is
loaded.
NONDESTRUCTIVE INPUT NO WAIT REQUEST
COMMAND CODE = 5
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Request header 13-BYTE |
+---------------------------------------------------------------------------+
| Byte read from device BYTE |
+---------------------------------------------------------------------------+
The driver must do the following:
Return a byte from the device.
Set the status word in the request header.
If the character device returns busy bit = 0, meaning there are characters in
buffer, the next character that would be read is returned. This character is
not removed from the input buffer, (that is, nondestructive input). This
call allows DOS 4.00 to look ahead one input character.
CHARACTER INPUT AND OUTPUT STATUS REQUESTS
COMMAND CODES = 6, 10
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Request header 13-BYTE |
+---------------------------------------------------------------------------+
The driver must do the following:
Perform the requested function.
Set the busy bit.
Set the status word in the request header.
The busy bit is set differently for output and input.
Output on Character Devices
If the busy bit is 1 on return, a write request would wait for completion of
a current request. If the busy bit is 0, no request is waiting or running.
Therefore, a write request would start immediately.
Input on Character Devices with a Buffer
If the busy bit is 1 on return, a read request goes to the physical device.
If the busy bit is 0, characters are in the device buffer and a read returns
quickly. This also indicates that the user has typed something. DOS 4.00
assumes that all character devices have a type-ahead input buffer. Devices
that do not have this buffer should always return busy = 0 so that DOS 4.00
does not loop endlessly, waiting for information to be put in a buffer that
does not exist.
CHARACTER INPUT AND OUTPUT FLUSH REQUESTS
COMMAND CODES = 7, 11
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Request header 13-BYTE |
+---------------------------------------------------------------------------+
This call tells the driver to flush (terminate) all pending requests of which
it has knowledge. Its primary use is to flush the input queue on character
devices.
The driver must set the status word in the Request Header upon return.
OPEN AND CLOSE REQUESTS
COMMAND CODES = 13, 14
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Request header 13-BYTE |
+---------------------------------------------------------------------------+
These calls are designed to give the device information about current file
activity on the device if bit 11 of the attribute word is set.
On block devices, these calls can be used to manage local buffering. The
device can keep a reference count. Every OPEN increases the reference count.
Every CLOSE decreases the device reference count. When the reference count
is 0, there are no open files on the device. Therefore, the device should
flush buffers inside the device to which it has written because the user can
change the media on a removable media drive. If the media has been changed,
reset the reference count to 0 without flushing the buffers.
These calls are more useful on character devices. The OPEN call can send a
device an initialization string. On a printer, the call can send a string to
set the font or the page size so the printer is always in a known state at
the start of an I/O stream.
Similarly, the CLOSE call can send a post string, such as a form feed, at the
end of an I/O stream.
Using IOCtl to set the preliminary and ending strings provides a flexible
mechanism for serial I/O device stream control.
REMOVABLE MEDIA REQUEST
COMMAND CODE = 15
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Request header 13-BYTE |
+---------------------------------------------------------------------------+
To use this call, set bit 11 of the attribute field to 1. Block devices can
use this call only by way of a subfunction of the IOCtl function call (44H).
This call is useful because it notifies a utility if it is dealing with a
removable or nonremovable media drive. For example, the FORMAT utility needs
to know whether a drive is removable or nonremovable because it displays
different versions of some prompts.
The information is returned in the busy bit of the status word. If the busy
bit is 1, the media is nonremovable. If the busy bit is 0, the media is
removable.
No error bit checking is performed. It is assumed that this call always
succeeds.
GENERIC IOCTL REQUEST
COMMAND CODE = 19
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Request header 13-BYTE |
+---------------------------------------------------------------------------+
| Major function BYTE |
+---------------------------------------------------------------------------+
| Minor function BYTE |
+---------------------------------------------------------------------------+
| Contents of SI WORD |
+---------------------------------------------------------------------------+
| Contents of DI WORD |
+---------------------------------------------------------------------------+
| Pointer to Generic IOCTL request packet DWORD |
+---------------------------------------------------------------------------+
The driver must:
Support the functions described under Generic IOCtl request
Maintain its own track table (TrackLayout).
See Appendix C, "I/O Control for Devices (IOCtl)" on page C-1 for a
description of the functions provided by generic IOCtl requests.
GET LOGICAL DEVICE REQUEST
COMMAND CODE = 23
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Request header 13-BYTE |
+---------------------------------------------------------------------------+
| Input (unit code) BYTE |
+---------------------------------------------------------------------------+
| Command code BYTE |
+---------------------------------------------------------------------------+
| Status WORD |
+---------------------------------------------------------------------------+
| Reserved DWORD |
+---------------------------------------------------------------------------+
SET LOGICAL DEVICE REQUEST
COMMAND CODE = 24
+---------------------------------------------------------------------------+
| FIELD LENGTH |
+---------------------------------------------------------------------------+
| Request header 13-BYTE |
+---------------------------------------------------------------------------+
| Input (unit code) BYTE |
+---------------------------------------------------------------------------+
| Command code BYTE |
+---------------------------------------------------------------------------+
| Status WORD |
+---------------------------------------------------------------------------+
| Reserved DWORD |
+---------------------------------------------------------------------------+
CLOCK$ DEVICE DRIVER EXAMPLE
This feature is a "Real-Time Clock" Board. To allow this board to be
integrated into the system for TIME and DATE, a special device driver is
specified by an attribute word, the CLOCK$ device. This device driver
defines and performs functions like any other character device driver. Most
functions will be set done bit, reset error bit, return. When a read or
write to this device occurs, 6 bytes are transferred. The first 2 bytes are
a word, which is the count of days since 1-1-80. The third byte is minutes;
the fourth is hours; the fifth is hundredths of seconds; and the sixth is
seconds. Reading the CLOCK$ device gets the date and time; writing to it
sets the date and time.
PART 3. APPENDIXES
Appendix A
APPENDIX A. DOS 4.00 INTERRUPTS 13 20H Program Terminate 21 21H Function Request 41 22H Terminate Address 46 23H Ctrl-Break Exit Address 53 24H Critical Error Handler Vector 83 25H/26H Absolute Disk Read/Write 287 27H Terminate but Stay Resident 353 28H-2EH Reserved for DOS 4.00 392 2FH Multiplex Interrupt 396 30H-3FH Reserved for DOS 4.00 695
APPENDIX A. DOS 4.00 INTERRUPTS
This chapter contains information to support use of the DOS 4.00 interrupts.
DOS 4.00 reserves interrupt types 20H to 3FH for its use. Absolute memory locations 80H to FFH are reserved by DOS 4.00. All interrupt values are in hexadecimal.
20H PROGRAM TERMINATE
Issue interrupt 20H to exit from a program. This vector transfers to the logic in DOS 4.00 to restore the terminate address, the Ctrl-Break address, and the critical error exit address to the values they had on entry to the program. All file buffers are flushed and all handles are closed. You should close all files changed in length (see function call 10H and 3EH) before issuing this interrupt. If the changed file is not closed, its length, date, and time are not recorded correctly in the directory.
For a program to pass a completion code or an error code when terminating, it must use either function call 4CH (Terminate a Process) or 31H (Terminate Process and Stay Resident). These two methods are preferred over using interrupt 20H, and the codes returned by them can be interrogated in batch processing. See function call 4CH for information on the ERRORLEVEL subcommand of batch processing.
IMPORTANT: Before you issue interrupt 20H, your program must ensure that the CS register contains the segment address of its program segment prefix.
21H FUNCTION REQUEST
Refer to each function call issued within 21H in Appendix B, "DOS 4.00 Function Calls" on page B-1.
22H TERMINATE ADDRESS
Control transfers to the address at this interrupt location when the program terminates. This address is copied into the program's Program Segment Prefix at the time the segment is created. You should not issue this interrupt; the EXEC function call does this for you.
23H CTRL-BREAK EXIT ADDRESS
If the user presses the Ctrl and Break keys during standard input, standard output, standard printer, or asynchronous communications adapter operations, an interrupt 23H is executed. If BREAK is on, the interrupt 23H is checked on most function calls (except calls 06H and 07H). If the user-written Ctrl-Break routine saves all registers, it may end with a return-from-interrupt instruction (IRET) to continue program execution.
If the user-written interrupt program returns with a long return, the carry flag is used to determine whether the program will be ended. If the carry flag is set, the program is ended, otherwise execution continues (as with a return by IRET).
If the user-written Ctrl-Break interrupt uses function calls 09H or 0AH, then &hat.C, carriage-return and linefeed are output. If execution is continued with an IRET, I/O continues from the start of the line.
When the interrupt occurs, all registers are set to the value they had when the original function call to DOS 4.00 was made. There are no restrictions on what the Ctrl-Break handler is allowed to do, including DOS 4.00 function calls, as long as the registers are unchanged if IRET is used.
When the program creates a new segment and loads in a second program it changes the Ctrl-Break address. The termination of the second program and return to the first causes the Ctrl-Break address to be restored to the value it had before execution of the second program. It is restored from the second program's Program Segment Prefix. You should not issue this interrupt.
24H CRITICAL ERROR HANDLER VECTOR
A critical error is returned when a DOS function cannot be performed. This error is frequently caused by a hardware condition, such as the printer being out of paper, a diskette drive door open, or a diskette out of space. When a critical error occurs within DOS 4.00, control is transferred with an interrupt 24H. On entry to the error handler, AH will have its bit 7=0 (high-order bit) if the error was a disk error (the most common occurrence), bit 7=1 if it was not.
BP:SI contains the address of a Device Header Control Block from which additional information can be retrieved. See page A-5.
The registers are set up for a retry operation, and an error code is in the lower half of the DI register with the upper half undefined. The error codes follow:
ERROR CODE MEANING 0 Attempt to write on write-protected diskette 1 Unknown unit 2 Drive not ready 3 Unknown command 4 Data error (CRC) 5 Bad request structure length 6 Seek error 7 Unknown media type 8 Sector not found 9 Printer out of paper A Write fault B Read fault C General failure
The user stack is in effect and contains the following from top to bottom:
IP DOS 4.00 registers from issuing INT 24H
CS FLAGS AX User registers at time of original BX INT 21H request CX DX SI DI BP DS ES IP From the original interrupt 21H CS from the user to DOS 4.00 FLAGS
The registers are set such that if an IRET is executed, DOS 4.00 responds according to (AL) as follows:
(AL) =0 ignore the error. =1 retry the operation. =2 terminate the program through interrupt 22H. =3 fail the system call in progress.
NOTE: Be careful when choosing ignore as a response because this causes DOS 4.00 to believe that an operation has completed successfully when it may not have.
To return control from the critical error handler to a user error routine, the following should occur:
Before an INT 24H occurs:
1. The user application initialization code should save the INT 24H vector and replace the vector with one pointing to the user error routine.
When the INT 24H occurs:
2. When the user error routine receives control, it should push the flag register onto the stack, and then execute a CALL FAR to the original INT 24H vector saved in step 1.
3. DOS 4.00 gives the appropriate prompt, and waits for the user input (Abort, Retry, Fail or Ignore). After the user input, DOS 4.00 returns control to the user error routine at the instruction following the CALL FAR.
4. The user error routine can now do any tasks necessary. To return to the original application at the point the error occurred, the error routine needs to execute an IRET instruction. Otherwise, the user error routine should remove the IP, CS, and Flag registers from the stack. Control can then be passed to the desired point.
Disk Errors
If it is a hard error on disk (AH bit 7=0), register AL contains the failing drive number (0 = drive A, and so on). AH bits 0-2 indicate the affected disk area and whether it was a read or write operation, as follows:
Bit 0=0 if read operation, 1 if write operation Bits 2-1 (affected disk area) 0 0 DOS 4.00 area 0 1 file allocation table 1 0 directory 1 1 data area
AH bits 3-5 indicate which responses are valid. They are:
Bit 3=0 if FAIL is not allowed =1 if FAIL is allowed Bit 4=0 if RETRY is not allowed =1 if RETRY is allowed Bit 5=0 if IGNORE is not allowed =1 if IGNORE is allowed
Handling of Invalid Responses
If IGNORE is specified (AL=0) and IGNORE is not allowed (bit 5=0), make the response FAIL (AL=3).
If RETRY is specified (AL=1) and RETRY is not allowed (bit 4=0), make the response FAIL (AL=3).
If FAIL is specified (AL=3) and FAIL is not allowed (bit 3=0), make the response END (AL=2).
Other Errors
If AH bit 7=1, the error occurred on a character device, or was the result of a bad memory image of the FAT. The device header passed in BP:SI can be examined to determine which case exists. If the attribute byte high-order bit indicates a block device, then the error was a bad FAT. Otherwise, the error is on a character device.
If a character device is involved, the contents of AL are unpredictable and the error code is in DI as above.
NOTES:
1. Retry five times before giving this routine control for disk errors. When the errors are in the FAT or a directory, retry three times.
2. For disk errors, this exit is taken only for errors occurring during an interrupt 21H function call. It is not used for errors during an interrupt 25H or 26H.
3. This routine is entered in a disabled state.
4. All registers must be preserved.
5. This interrupt handler should refrain from using DOS 4.00 function calls. If necessary, it may use calls 01H through 0CH, 30H, and 59H. Use of any other call destroys the DOS 4.00 stack and leaves DOS 4.00 in an unpredictable state.
6. The interrupt handler must not change the contents of the device header.
7. If the interrupt handler handles errors itself rather than returning to DOS 4.00, it should restore the application program's registers from the stack, remove all but the last three words on the stack, then issue an IRET. This will return to the program immediately after the INT 21H that experienced the error. Note that if this is done, DOS 4.00 will be in an unstable state until a function call higher than 0CH is issued; therefore, it is not recommended.
The recommended way to end a critical error is to use FAIL and then test the extended error code of the INT 21H.
8. IGNORE requests (AL=0) are converted to FAIL for critical errors that occur on FAT or DIR sectors.
9. Refer to "Responding to Errors" on page B-5 and "Extended Error Codes" on page B-5 for information on how to obtain additional error information.
10. For DOS 4.00, IGNORE requests (AL=0) are converted to FAIL requests for certain critical errors (50-79).
The device header pointed to by BP:SI is formatted as follows:
+---------------------------------------------------------------------------+ | DWORD Pointer to next device (FFFFH if last device) | +---------------------------------------------------------------------------+ | WORD Attributes: | | Bit 15 = 1 if character device | | = 0 if block device | | If bit 15 is 1: | | Bit 0 = 1 if current standard input | | Bit 1 = 1 if current standard output | | Bit 2 = 1 if current NULL device | | Bit 3 = 1 if current CLOCK device | | Bit 14 is the IOCtl bit | +---------------------------------------------------------------------------+ | WORD pointer to device driver strategy entry point. | +---------------------------------------------------------------------------+ | WORD pointer to device driver interrupt entry point. | +---------------------------------------------------------------------------+ | 8-BYTE character device named field for block devices. The first byte is | | the number of units. | +---------------------------------------------------------------------------+
To tell if the error occurred on a block or character device, look at bit 15 in the attribute field (WORD at BP:SI+4).
If the name of the character device is desired, look at the eight bytes starting at BP:SI+10.
25H/26H ABSOLUTE DISK READ/WRITE
Interrupt vectors 25H and 26H transfer control to the device driver. They have been extended to allow direct access to media greater than 32MB in size. Their use of the CX register is what distinguishes them from the conventional 25H and 26H interrupts. Note that if the conventional format parameters are used in an attempt to access media greater than 32MB, an error code of 0207H is returned in AX.
The request for extended 25H or 26H is:
MOV AL,DRIVE ; Drive number to process
- 0 = A
- 1 = B
- 2 = C . . .
LDS BX,PACKET ; Parameter list MOV CX,-1 ; Indicates extended format INT 25H or 26H ; Issue request to DOS 4.00 POP AX ; Discard stack word JC ERROR ; Error code returned in AX
PACKET LABEL BYTE ; Control packet DD RBA ; RBA of first sector
- (0 origin)
DW COUNT ; Number of sectors to I/O DD BUFFER ; Data buffer
On return, the original flags are still on the stack (put there by the INT instruction). This is necessary because return information is passed back in the current flags. Be sure to pop the stack to prevent uncontrolled growth.
WARNING: IF DISK I/O HANDLED BY THIS INTERRUPT EXCEEDS THE LIMIT IMPOSED BY THE 64KB DIRECT MEMORY ACCESS BOUNDARY, UNPREDICTABLE RESULTS CAN OCCUR. WE RECOMMEND YOU CAREFULLY CHECK THE SECTOR SIZE AND THE NUMBER OF SECTORS TO BE READ OR WRITTEN TO BEFORE ISSUING THIS CALL.
The number of sectors specified is transferred between the given drive and the transfer address. Logical sector numbers (LSN) are obtained by numbering each sector sequentially starting from track 0, head 0, sector 1 (logical sector 0) and continuing along the same head, then to the next head until the last sector on the last head of the track is counted. Thus, logical sector 1 is track 0, head 0, sector 2; logical sector 2 is track 0, head 0, sector 3; and so on. Numbering continues with sector 1 on head 0 of the next track. Note that although the sectors are sequentially numbered (for example, sectors 2 and 3 on track 0 in the example above), they may not be physically adjacent on the disk, because of interleaving. Note that the mapping is different from that used by DOS version 1.10 for dual-sided diskettes.
All registers except the segment registers are destroyed by this call. If the transfer was successful, the carry flag (CF) is 0. If the transfer was not successful CF=1 and (AX) indicate the error as follows. (AL) is the DOS 4.00 error code that is the same as the error code returned in the low byte of DI when an interrupt 24H is issued, and (AH) contains:
80H Attachment failed to respond 40H SEEK operation failed 08H Bad CRC on diskette read 04H Requested sector not found 03H Write attempt on write-protected diskette 02H Error other than types listed above
WARNING: BEFORE ISSUING THIS INTERRUPT TO REMOVABLE MEDIA, THE MEDIA IN THE DRIVE MUST BE ESTABLISHED CORRECTLY. THIS CAN BE ACCOMPLISHED BY ISSUING EITHER AN INT 21H GENERIC IOCTL (AH=44H), WITH A REQUEST TO RETURN THE BPB THAT BUILD BPB RETURNS; OR AN INT 21H GET CURRENT DIRECTORY (AH=47H).
27H TERMINATE BUT STAY RESIDENT
This vector is used by programs that are to remain resident when COMMAND.COM regains control.
DOS 4.00 function call 31H is the preferred method to cause a program to remain resident, because this allows return information to be passed. It allows a program larger than 64KB to remain resident. After initializing itself, the program must set DX to its last address plus one, relative to the program's initial DS or ES value (the offset at which other programs can be loaded), and then execute an interrupt 27H. DOS 4.00 then considers the program as an extension of itself, so the program is not overlaid when other programs are executed. This concept is useful for loading programs such as user-written interrupt handlers that must remain resident.
NOTES:
1. This interrupt must not be used by .EXE programs that are loaded into the high end of memory.
2. This interrupt restores the interrupt 22H, 23H, and 24H vectors in the same manner as interrupt 20H. Therefore, it cannot be used to install permanently resident Ctrl-Break or critical error handler routines.
3. The maximum size of memory that can be made resident by this method is 64KB.
4. Memory can be used more efficiently if the block containing a copy of the environment is deallocated before terminating. This can be done by loading ES with the segment contained in 2C of the PSP, and issuing function call 49H (Free Allocated Memory).
5. DOS 4.00 function call 4CH allows the terminating program to pass a completion (or error) code to DOS 4.00, which can be interpreted within batch processing (see function call 31H).
6. Terminate-but-stay-resident function calls do not automatically close files.
28H-2EH RESERVED FOR DOS 4.00
These interrupts are reserved for DOS 4.00 use.
2FH MULTIPLEX INTERRUPT
Interrupt 2FH is the multiplex interrupt. A general interface is defined between two processes. The specific application using interrupt 2FH defines specific functions and parameters.
Every multiplex interrupt handler is assigned a specific multiplex number. The multiplex number is specified in the AH register. The specific function that the handler is to perform is specified in the AL register. Other parameters are placed in the other registers, as needed. The handlers are chained into the interrupt 2FH interrupt vector. There is no defined method for assigning a multiplex number to a handler. You must pick one. To avoid
a conflict if two applications choose the same multiplex number, the multiplex numbers used by an application should be patchable.
The multiplex numbers AH=00H through BFH are reserved for DOS 4.00. Applications should use multiplex numbers C0H through FFH.
NOTE: When in the chain for interrupt 2FH, if your code calls DOS 4.00 or if you execute with interrupts enabled, your code must be reentrant and recursive.
Function Codes
AH=1
AH=1 is the resident part of PRINT.
The following table contains the function codes that you can specify in AL to request the resident portion of print to perform a specific function:
+---------------------------------------------------------------------------+ | FUNCTION | | CODES DESCRIPTION | +---------------------------------------------------------------------------+ | 0 Get installed state | +---------------------------------------------------------------------------+ | 1 Submit file | +---------------------------------------------------------------------------+ | 2 Cancel file | +---------------------------------------------------------------------------+ | 3 Cancel all files | +---------------------------------------------------------------------------+ | 4 Status | +---------------------------------------------------------------------------+ | 5 End of status | +---------------------------------------------------------------------------+
Print Error Codes
The following table contains the error codes that are returned from the resident portion of print.
+---------------------------------------------------------------------------+ | ERROR | | CODES DESCRIPTION | +---------------------------------------------------------------------------+ | 1 Invalid function | +---------------------------------------------------------------------------+ | 2 File not found | +---------------------------------------------------------------------------+ | 3 Path not found | +---------------------------------------------------------------------------+ | 4 Too many open files | +---------------------------------------------------------------------------+ | 5 Access denied | +---------------------------------------------------------------------------+ | 6 Queue full | +---------------------------------------------------------------------------+ | 9 Busy | +---------------------------------------------------------------------------+ | 12 Name too long | +---------------------------------------------------------------------------+ | 15 Invalid drive | +---------------------------------------------------------------------------+
AL=0 Get Installed State
This call must be defined by all interrupt 2FH handlers. It is used by the caller of the handler to determine if the handler is present. On entry, AL=0, AH=1. On return, AL contains the installed state as follows:
AL=0 Not installed, permissible to install
AL=1 Not installed, not permissible to install
AL=FF Installed
AL=1 Submit File
On entry, AL=1, AH=1, and DS:DX points to the submit packet. A submit packet contains the level (BYTE) and a pointer to the ASCIIZ string (DWORD in offset segment form). The level value for DOS 4.00 is 0. The ASCIIZ string must contain the drive, path, and filename of the file you want to print. The filename cannot contain global filename characters. AL=2 Cancel File
On entry, AL=2, AH=1, and DS:DX points to the ASCIIZ string for the print file you want to cancel. Global filename characters are allowed in the filename. AL=3 Cancel all Files
On entry, AL=3 and AH=1.
AL=4 Status
This call holds the jobs in the print queue so that you can scan the queue. Issuing any other code releases the jobs. On entry, AL=4, AH=1. On return, DX contains the error count. The error count is the number of consecutive failures PRINT had while trying to output the last character. If there are no failures, the number is 0. DS:SI points to the print queue. The print queue consists of a series of filename entries. Each entry is 64 bytes long. The first entry in the queue is the file currently being printed. The end of the queue is marked by a queue entry having a null as the first character.
AL=5 End of Status: Issue this call to release the queue from call 4. On entry, AL=5 and AH=1. On return, AX contains the error codes. For information on the error codes returned, refer to "Print Error Codes" on page A-10.
AL=F8-FF Reserved by DOS 4.00
AH=6
AH=6 is the resident part of ASSIGN. The Get Installed State function (AL=0) is supported.
AH=8H, 10H, 12H, 13H Reserved by DOS 4.00
AH=B7H
AH=B7H is the resident part of APPEND. The Get Installed State function (AL=0) is supported.
AL=2 Get APPEND version This call is for distinguishing between the PC LAN APPEND and the DOS 4.00 APPEND. On return, if AX=FFFFH then the DOS 4.00 APPEND is loaded.
AL=4 Get APPEND Path Pointer (DOS 4.00 APPEND only) On return ES:DI points to the currently active APPEND path.
AL=6 Get APPEND Function State (DOS 4.00 APPEND only)
BX is returned with bits set indicating if APPEND is currently enabled and what functions are in effect.
+--------+------------------------------------------------------------------+ | BIT | FUNCTION IN EFFECT IF BIT IS ON | +--------+------------------------------------------------------------------+ | 0 | APPEND enabled | +--------+------------------------------------------------------------------+ | 13 | /PATH | +--------+------------------------------------------------------------------+ | 14 | /E | +--------+------------------------------------------------------------------+ | 15 | /X | +--------+------------------------------------------------------------------+
NOTE: The functions in effect do not change whether or not APPEND is disabled.
AL=7 Set function state (DOS 4.00 APPEND only)
On input BX is the new setting for all functions. The suggested procedure is to get the current function state, turn on or turn off the desired bits, then use this call to set the function state.
AL=11H Set Return Found Name State (DOS 4.00 APPEND only)
On request AL=17, a process system state flag is set. If this flag is set, then on the next ASCIIZ 3DH, 43H or 6CH function call within Interrupt 21H that APPEND processes, APPEND returns the name it finds to the application filename buffer. This name may be different from the one the application offered. The application must provide enough space for the found name. After APPEND has processed an
Interrupt 21H, it resets the Return Found Name state. An example of this process follows:
MOV AH,0B7H ; Indicate APPEND MOV AL,0 ; Get installed state INT 2FH CMP AL,0 ; APPEND installed? JE NOT_INSTALLED
MOV AH,0B7H ; Indicate APPEND MOV AL,2 ; Get APPEND version INT 2FH CMP AX,-1 ; DOS version? PC_LAN_APPEND ; AX<> -1 means PC LAN JNE APPEND
- The following functions are valid only if DOS 4.00 APPEND
MOV AH,0B7H ; Indicate APPEND MOV AL,4 ; Get APPEND path pointer INT 2FH
- ES
- DI = address of APPEND path
- (Buffer is 128 characters long)
MOV AH,0B7H ; Indicate APPEND MOV AL,6 ; Get function state INT 2FH
- BX = function state
- 8000H = /X is on
- 4000H = /E is on
- 2000H = /PATH is on
- 0001H = APPEND enabled
- If off, similar to null
- APPEND path
- Set on by any non-status
- occurrence of APPEND
MOV AH,0B7H ; Indicate APPEND MOV AL,7 ; Set function state MOV BX,state ; New state INT 2FH
MOV AH,0B7H ; Indicate APPEND MOV AL,11H ; Set Return Found
- Name state
INT 2FH
Example 2FH Handler
MYNUM DB X ; X = The specific AH
- multiplex number.
INT 2F NEXT DD ? ; Chain location INT 2F:
ASSUME DS:NOTHING,ES:NOTHING,SS:NOTHING
CMP AH,MYNUM JE MINE JMP INT 2F NEXT ; Chain to next
- 2FH Handler
MINE:
CMP AL,0F8H JB DO FUNC IRET ; IRET on reserved
- functions
DO FUNC:
OR AL,AL JNE NON INSTALL ; Non Get Installed
- State request
MOV AL,0FFH ; Say I'm here IRET ; All done
NON INSTALL: . . .
Installing the Handler
The following example contains the functions necessary to install a handler:
MOV AH,MYNUM XOR AL,AL INT 2FH ; Ask if already
- installed
OR AL,AL JZ OK INSTALL
BAD INSTALL: ; Handler already installed .sp 3 OK INSTALL: ; Install my
- handler
MOV AL,2FH MOV AH,GET INTERRUPT VECTOR INT 21H ; Get multiplex
- vector
MOV WORD PTR INT 2F NEXT+2,ES MOV WORD PTR INT 2F NEXT,BX MOV DX,OFFSET INT 2F MOV AL,2FH MOV AH,SET INTERRUPT VECTOR INT 21H ; Set multiplex
- vector
. . .
30H-3FH RESERVED FOR DOS 4.00
These interrupts are reserved for DOS 4.00 use.
Appendix B
APPENDIX B. DOS 4.00 FUNCTION CALLS 100
Using DOS 4.00 Function Calls 219
Program Code Fragments 230
.COM Programs 236
DOS 4.00 Registers 256
Responding to Errors 340
Extended Error Codes 355
00H -- Program Terminate 518
01H -- Console Input with Echo 546
02H -- Display Output 581
03H -- Auxiliary Input 603
04H -- Auxiliary Output 631
05H -- Printer Output 655
06H -- Direct Console I/O 672
07H -- Direct Console Input Without Echo 720
08H -- Console Input Without Echo 753
09H -- Display String 786
0AH -- Buffered Keyboard Input 815
0BH -- Check Standard Input Status 848
0CH -- Clear Keyboard Buffer and Invoke a Keyboard Function 868
0DH -- Disk Reset 885
0EH -- Select Disk 904
0FH -- Open File 937
10H -- Close File 985
11H -- Search for First Entry 1022
12H -- Search for Next Entry 1099
13H -- Delete File 1149
14H -- Sequential Read 1193
15H -- Sequential Write 1240
16H -- Create File 1286
17H -- Rename File 1330
19H -- Current Disk 1380
1AH -- Set Disk Transfer Address 1400
1BH -- Allocation Table Information 1425
1CH -- Allocation Table Information for Specific Device 1453
21H -- Random Read 1489
22H -- Random Write 1541
23H -- File Size 1599
24H -- Set Relative Record Field 1642
25H -- Set Interrupt Vector 1668
26H -- Create New Program Segment 1695
27H -- Random Block Read 1725
28H -- Random Block Write 1787
29H -- Parse Filename 1847
2AH -- Get Date 1918
2BH -- Set Date 1946
2CH -- Get Time 1979
2DH -- Set Time 2015
2EH -- Set/Reset Verify Switch 2051
2FH -- Get Disk Transfer Address (DTA) 2085
30H -- Get DOS Version Number 2108
31H -- Terminate Process and Remain Resident 2138
33H -- Get/Set System Value 2175
35H -- Get Interrupt Vector 2235
36H -- Get Disk Free Space 2262
38H -- Get or Set Country Dependent Information 2318
39H -- Create Subdirectory (MKDIR) 2431
3AH -- Remove Subdirectory (RMDIR) 2466
3BH -- Change the Current Directory (CHDIR) 2498
3CH -- Create a File (CREAT) 2530
3DH -- Open a File 2577
3EH -- Close a File Handle 2812
3FH -- Read from a File or Device 2840
40H -- Write to a File or Device 2886
41H -- Delete a File from a Specified Directory (UNLINK) 2938
42H -- Move File Read Write Pointer (LSEEK) 2971
43H -- Change File Mode (CHMOD) 3035
44H -- I/O Control for Devices 3092
45H -- Duplicate a File Handle (DUP) 3103
46H -- Force a Duplicate of a Handle (FORCDUP) 3137
47H -- Get Current Directory 3170
48H -- Allocate Memory 3202
49H -- Free Allocated Memory 3237
4AH -- Modify Allocated Memory Blocks (SETBLOCK) 3263
4BH -- Load or Execute a Program (EXEC) 3303
4CH -- Terminate a Process (EXIT) 3442
4DH -- Get Return Code of a Subprocess (WAIT) 3466
4EH -- Find First Matching File (FIND FIRST) 3494
4FH -- Find Next Matching File (FIND NEXT) 3567
54H -- Get Verify Setting 3606
56H -- Rename a File 3628
57H -- Get/Set File's Date and Time 3669
59H -- Get Extended Error 3714
5AH -- Create Unique File 3785
5BH -- Create New File 3839
5CH -- Lock/Unlock File Access 3878
5E00H -- Get Machine Name 3972
5E02H -- Set Printer Setup 4006
5E03H -- Get Printer Setup 4051
5F02H -- Get Redirection List Entry 4096
5F03H -- Redirect Device 4169
5F04H -- Cancel Redirection 4259
62H -- Get Program Segment Prefix Address 4305
65H -- Get Extended Country Information 4328
66H -- Get/Set Global Code Page 4451
67H -- Set Handle Count 4494
68H -- Commit File 4539
6CH -- Extended Open/Create 4562
APPENDIX B. DOS 4.00 FUNCTION CALLS
NUMBER FUNCTION NAME
00H Program terminate
01H Console input with echo
02H Display output
03H Auxiliary input
04H Auxiliary output
05H Printer output
06H Direct console I/O
07H Direct console input without echo
08H Console input without echo
09H Display string
0AH Buffered keyboard input
0BH Check standard input status
0CH Clear keyboard buffer, invoke a keyboard function
0DH Disk reset
0EH Select disk
0FH Open file
10H Close file
11H Search for first entry
12H Search for next entry
13H Delete file
14H Sequential read
15H Sequential write
16H Create file
17H Rename file
18H Reserved by DOS 4.00
19H Current disk
1AH Set disk transfer address
1BH Allocation table information
1CH Allocation table information for specific device
1DH Reserved by DOS 4.00
1EH Reserved by DOS 4.00
1FH Reserved by DOS 4.00
20H Reserved by DOS 4.00
21H Random read
22H Random write
23H File size
24H Set relative record field
25H Set interrupt vector
26H Create new program segment
27H Random block read
28H Random block write
29H Parse filename
2AH Get date
2BH Set date
2CH Get time
2DH Set time
2EH Set/reset verify switch
2FH Get disk transfer address
30H Get DOS 4.00 version number
31H Terminate process and remain resident
32H Reserved by DOS 4.00
33H Get/Set system value
34H Reserved by DOS 4.00
35H Get interrupt vector
36H Get disk free space
37H Reserved by DOS 4.00
38H Get/set country dependent information
39H Create subdirectory (MKDIR)
3AH Remove subdirectory (RMDIR)
3BH Change current directory (CHDIR)
3CH Create a file (CREAT)
3DH Open a file
3EH Close a file handle
3FH Read from a file or device
40H Write to a file or device
41H Delete a file from a specified directory (UNLINK)
42H Move file read/write pointer (LSEEK)
43H Change file mode (CHMOD)
44H I/O control for devices (IOCtl)
45H Duplicate a file handle (DUP)
46H Force a duplicate of a file handle (FORCDUP)
47H Get current directory
48H Allocate memory
49H Free allocated memory
4AH Modify allocated memory blocks (SETBLOCK)
4BH Load or execute a program (EXEC)
4CH Terminate a process (EXIT)
4DH Get return code of a subprocess (WAIT)
4EH Find first matching file (FIND FIRST)
4FH Find next matching file (FIND NEXT)
50H Reserved by DOS 4.00
51H Reserved by DOS 4.00
52H Reserved by DOS 4.00
53H Reserved by DOS 4.00
54H Get verify setting
55H Reserved by DOS 4.00
56H Rename a file
57H Get/set a file's date and time
58H Reserved for DOS 4.00
59H Get extended error
5AH Create unique file
5BH Create new file
5CH Lock/unlock file access
5DH Reserved by DOS 4.00
5E00H Get machine name
5E02H Set printer setup
5E03H Get printer setup
5F02H Get redirection list entry
5F03H Redirect device
5F04H Cancel redirection
60H Reserved by DOS 4.00
61H Reserved by DOS 4.00
62H Get PSP address
63H Reserved by DOS 4.00
64H Reserved by DOS 4.00
65H Get extended country information
66H Get/set global code page
67H Set handle count
68H Commit file
69H Reserved by DOS 4.00
6AH Reserved
6BH Reserved by DOS 4.00
6CH Extended open/create
USING DOS 4.00 FUNCTION CALLS
Most function calls require input to be passed to them in registers. After
setting the appropriate register values, issue the function calls in either
of the following ways:
The preferred method is to place the function number in AH and issue
interrupt 21H.
Place the function number in AH and execute a call to offset 50H in your
program segment prefix.
PROGRAM CODE FRAGMENTS
In each of the function call descriptions in this chapter, the input, output
and method of use are described using a small program code fragment. These
fragments are written in IBM PC Assembler Language.
.COM PROGRAMS
The descriptions assume that the program is an .EXE, not a .COM program. If
a .COM program is desired, do not include either of the following
instructions:
MOV ES,SEG --
or
MOV DS,SEG --
NOTES:
1. Some FCB function calls do not permit invalid characters (0DH-29H).
2. Device names cannot end in a colon.
3. The contents of the AX register can be altered by any of the function
calls. Even though no error code is returned in AX, it is possible that
AX has been changed.
DOS 4.00 REGISTERS
DOS 4.00 uses the following registers, pointers, and flags when executing
interrupts and function calls:
+---------------------------------------------------------------------------+
| REGISTER GENERAL |
| DEFINITION REGISTERS |
+---------------------------------------------------------------------------+
| AX Accumulator (16-bit) |
| AH Accumulator high-order byte (8-bit) |
| AL Accumulator low-order byte (8-bit) |
+---------------------------------------------------------------------------+
| BX Base (16-bit) |
| BH Base high-order byte (8-bit) |
| BL Base low-order byte (8-bit) |
+---------------------------------------------------------------------------+
| CX Count (16-bit) |
| CH Count high-order byte (8-bit) |
| CL Count low-order byte (8-bit) |
+---------------------------------------------------------------------------+
| DX Data (16-bit) |
| DH Data high-order (8-bit) |
| DL Data low-order (8-bit) |
+---------------------------------------------------------------------------+
| Flags OF,DF,IF,TF,SF,ZF,AF,PF,CF |
+---------------------------------------------------------------------------+
+---------------------------------------------------------------------------+
| REGISTER |
| DEFINITION POINTERS |
+---------------------------------------------------------------------------+
| SP Stack pointer (16-bit) |
+---------------------------------------------------------------------------+
| BP Base pointer (16-bit) |
+---------------------------------------------------------------------------+
| IP Instruction pointer (16-bit) |
+---------------------------------------------------------------------------+
+---------------------------------------------------------------------------+
| REGISTER SEGMENT |
| DEFINITION REGISTERS |
+---------------------------------------------------------------------------+
| CS Code segment (16-bit) |
+---------------------------------------------------------------------------+
| DS Data segment (16-bit) |
+---------------------------------------------------------------------------+
| SS Stack segment (16-bit) |
+---------------------------------------------------------------------------+
| ES Extra segment (16-bit) |
+---------------------------------------------------------------------------+
+---------------------------------------------------------------------------+
| REGISTER INDEX |
| DEFINITION REGISTERS |
+---------------------------------------------------------------------------+
| DI Destination index (16-bit) |
+---------------------------------------------------------------------------+
| SI Source index (16-bit) |
+---------------------------------------------------------------------------+
Register Numbering Convention
Each register is 16 bits long and is divided into a high and low byte. Each
byte is 8 bits long. The bits are numbered from right to left. The low byte
contains bits 0 through 7 and the high byte contains bits 8 through 15. The
chart below shows the hexadecimal values assigned to each bit.
+--------------------------------------------------------------------------+
| High Byte Low Byte |
+--------------------------------------------------------------------------+
| Bit 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 |
+--------------------------------------------------------------------------+
| Hex value 8 4 2 1 8 4 2 1 8 4 2 1 8 4 2 1 |
+--------------------------------------------------------------------------+
DOS 4.00 Internal Stack
When DOS 4.00 gains control, it switches to an internal stack. User
registers are preserved unless information is passed back to the requester as
indicated in the specific requests. The user stack needs to be sufficient to
accommodate the interrupt system. It is recommended that the user stack be
200H in addition to what the user needs.
RESPONDING TO ERRORS
Handle function calls report an error by setting the carry flag and returning
the error code in AX. FCB function calls report an error by returning FFH in
AL.
Extended error support (59H) provides a common set of error codes and
specific error information such as error classification, location, and
recommended action. In most critical cases, applications can analyze the
error code and take specific action. Recommended actions are intended for
programs that do not understand the error codes. Programs can take advantage
of extended error support both from interrupt 24H critical error handlers and
after issuing interrupt 21H function calls. Do not code to specific error
codes.
EXTENDED ERROR CODES
HEXADECIMAL DECIMAL
CODE CODE MEANING
01H 1 Invalid function number
02H 2 File not found
03H 3 Path not found
04H 4 Too many open files (no handles left)
05H 5 Access denied
06H 6 Invalid handle
07H 7 Memory control blocks destroyed
08H 8 Insufficient memory
09H 9 Invalid memory block address
0AH 10 Invalid environment
0BH 11 Invalid format
0CH 12 Invalid access code
0DH 13 Invalid data
0EH 14 Reserved
0FH 15 Invalid drive was specified
10H 16 Attempt to remove the current directory
11H 17 Not same device
12H 18 No more files
13H 19 Attempt to write on write-protected diskette
14H 20 Unknown unit
15H 21 Drive not ready
16H 22 Unknown command
17H 23 Cyclic redundancy check (CRC) -- part of diskette
is bad
18H 24 Bad request structure length
19H 25 Seek error
1AH 26 Unknown media type
1BH 27 Sector not found
1CH 28 Printer out of paper
1DH 29 Write fault
1EH 30 Read fault
1FH 31 General failure
20H 32 Sharing violation
21H 33 Lock violation
22H 34 Invalid disk change
23H 35 FCB unavailable
24H 36 Sharing buffer overflow
25H 37 Reserved by DOS 4.00
26H 38 Unable to complete file operation
27H-31H 39-49 Reserved by DOS 4.00
50H 80 File exists
51H 81 Reserved
52H 82 Cannot make directory entry
53H 83 Fail on INT 24
54H 84 Too many redirections
55H 85 Duplicate redirection
56H 86 Invalid password
57H 87 Invalid parameter
58H 88 Network data fault
59H 89 Function not supported by network
HEXADECIMAL DECIMAL
CODE CODE MEANING
5AH 90 Required system component not installed
Extended Error Codes
HEXADECIMAL DECIMAL
CODE CODE MEANING
32H 50 Network request not supported
33H 51 Remote computer not listening
34H 52 Duplicate name on network
35H 53 Network path not found
36H 54 Network busy
37H 55 Network device no longer exists
38H 56 NETBIOS command limit exceeded
39H 57 System error; NETBIOS error
3AH 58 Incorrect response from network
3BH 59 Unexpected network error
3CH 60 Incompatible remote adapter
3DH 61 Print queue full
3EH 62 Not enough space for print file
3FH 63 Print file was cancelled
40H 64 Network name was deleted
41H 65 Access denied
42H 66 Network device type incorrect
43H 67 Network name not found
44H 68 Network name limit exceeded
45H 69 NETBIOS session limit exceeded
46H 70 Sharing temporarily paused
47H 71 Network request not accepted
48H 72 Print or disk redirection is paused
49H-4FH 73-79 Reserved
Error Classes
HEXADECIMAL DECIMAL
VALUE VALUE DESCRIPTION
01H 1 OUT OF RESOURCE: Example: out of space or
channels.
02H 2 TEMPORARY SITUATION: Something expected to
disappear with time. This is not an error
condition, but a temporary situation such as a
locked file.
03H 3 AUTHORIZATION: Permission problem.
04H 4 INTERNAL: Internal error in system software.
Probable problem with system software rather than a
user or system failure.
HEXADECIMAL DECIMAL
VALUE VALUE DESCRIPTION
05H 5 HARDWARE FAILURE: A serious problem not the fault
of user program.
06H 6 SYSTEM FAILURE: Serious failure of system software
not the fault of the user, such as missing or
incorrect configuration files.
07H 7 APPLICATION PROGRAM ERROR: Inconsistent requests.
08H 8 NOT FOUND: File or item not found. Inconsistent
requests.
09H 9 BAD FORMAT: File or value in invalid format or
type; unsuitable.
0AH 10 LOCKED: Locked file or item.
0BH 11 MEDIA: Media failure such as incorrect disk, CRC
error, or defective media.
0CH 12 ALREADY EXISTS: Duplication error, such as
declaring a machine name that already exists.
0DH 13 UNKNOWN: Classification does not exist or is
inappropriate.
Actions
HEXADECIMAL DECIMAL
CODE CODE DESCRIPTION
01H 1 RETRY: Retry a few times, then prompt user to
determine if the program should continue or be
terminated.
02H 2 DELAY RETRY: Retry several times after pause, then
prompt user to determine if the program should
continue or be terminated.
03H 3 USER: If the input was entered by a user, advise
reentry. The error, however, may have occurred in
the program itself, such as a bad drive letter or
bad filename specification.
04H 4 ABORT: Abort application with cleanup. The
application cannot proceed, but the system is in an
orderly state and it is safe to stop the
application.
05H 5 IMMEDIATE EXIT: Stop application immediately
without clearing registers. Do not use the
application to close files or update indexes, but
exit as soon as possible.
06H 6 IGNORE: Ignore.
07H 7 RETRY AFTER USER INTERVENTION: The user needs to
perform some action such as removing a diskette and
inserting a different one. Then retry the
operation.
Locus (Location)
HEXADECIMAL DECIMAL
VALUE VALUE DESCRIPTION
01H 1 UNKNOWN: Not specific; not appropriate.
02H 2 BLOCK DEVICE: Related to random access mass disk
storage.
03H 3 NET: Related to the network.
04H 4 SERIAL DEVICE: Related to serial devices.
05H 5 MEMORY: Related to random access memory.
00H --
PROGRAM TERMINATE
PURPOSE
Stops the execution of a program.
EXAMPLE
MOV AH,00H ; Function Call -- Terminate Program
INT 21H ; Issue request to DOS
; No return
COMMENTS
The terminate, Ctrl-Break, and critical error exit addresses are restored to
the values they had on entry to the terminating program, from the values
saved in the program segment prefix. All file buffers are flushed and the
handles opened by the process are closed. Any files that have changed in
length and not closed are not recorded properly in the directory. Control
transfers to the terminate address. This call performs exactly the same
function as interrupt 20H. It is the program's responsibility to ensure that
the CS register contains the segment address of its program segment prefix
control block before calling this function.
Function 4CH -- Terminate a Process is the preferred method for ending a
program.
01H --
CONSOLE INPUT WITH ECHO
PURPOSE
Waits for a character to be read at the standard input device (unless one is
ready), then echoes the character to the standard output device and returns
the character in AL.
EXAMPLE
MOV AH,01H ; Function Call -- keyboard input
INT 21H ; Issue request to DOS
MOV Char,AL ; Save character
CMP AL,0 ; Extended character ?
JNE Normal Char ; No!
MOV AH,01H ; Function Call -- keyboard input
INT 21H ; Issue request to DOS
MOV ExtChar,AL ; Save extended character
Normal Char:
Character LABEL WORD ; Complete character
Char DB ? ; Character buffer
ExtChar DB ? ; Character buffer
COMMENTS
The character is checked for a Ctrl-Break. If Ctrl-Break is detected, an
interrupt 23H is executed.
For function call 01H, extended ASCII codes require two function calls. The
first call returns 00H as an indicator that the next call will return an
extended code.
02H --
DISPLAY OUTPUT
PURPOSE
Outputs the character in DL to the standard output device.
EXAMPLE
MOV AH,02H ; Function Call -- Display Output
MOV DL,Char ; Get character to display
INT 21H ; Issue request to DOS
CHAR DB ? ; Character buffer
COMMENTS
If the character in DL is a backspace (08), the cursor is moved left one
position (nondestructive). If a Ctrl-Break is detected after the output, an
interrupt 23H is executed.
03H --
AUXILIARY INPUT
PURPOSE
Waits for a character from the standard auxiliary device, then returns that
character in AL.
EXAMPLE
MOV AH,03H ; Function Call -- Auxiliary Input
INT 21H ; Issue request to DOS
MOV Char,AL ; Save character
CHAR DB ? ; Character buffer
COMMENTS
Auxiliary (AUX) support is unbuffered and noninterrupt driven.
At startup, DOS 4.00 initializes the first auxiliary port to 2400 baud, no
parity, one-stop bit, and 8-bit word.
The auxiliary function calls (03H and 04H) do not return status or error
codes. For greater control, you should use the ROM BIOS routine (interrupt
14H) or write an AUX device driver and use IOCtl.
04H --
AUXILIARY OUTPUT
PURPOSE
Outputs the character in DL to the standard auxiliary device.
EXAMPLE
MOV AH,04H ; Function Call -- Auxiliary Output
MOV DL,Char ; Get character to output
INT 21H ; Issue request to DOS
; Nothing returned
CHAR DB ? ; Character buffer
COMMENTS
If the character in DL is a backspace (08), the cursor is moved left one
position (nondestructive). If a Ctrl-Break is detected after the output, an
interrupt 23H is executed.
05H --
PRINTER OUTPUT
PURPOSE
Outputs the character in DL to the standard printer device.
EXAMPLE
MOV AH,05H ; Function Call -- Printer Output
MOV DL,Char ; Get character to output
INT 21H ; Issue request to DOS
; Nothing returned
CHAR DB ? ; Character buffer
06H --
DIRECT CONSOLE I/O
PURPOSE
Gets a character from the standard input device if one is ready, or outputs a
character to the standard output device.
EXAMPLES
In loop:
MOV AH,06H ; Function Call -- Direct Console I/O
MOV DL,-1 ; 0FFH for input
INT 21H ; Issue request to DOS
JZ In loop ; No character yet on input
MOV Char,AL ; Save character
CMP AL,0 ; Extended Character ?
JNE Normal Char ; No!
MOV AH,07H ; Function Call -- Keyboard Input
INT 21H ; Issue request to DOS
MOV ExtChar,AL ; Save extended character
Normal Char:
or
MOV AH,06H ; Function Call -- Direct Console I/O
MOV DL,Char ; Get character to display (not 0FFH)
INT 21H ; Issue request to DOS
Character LABEL WORD ; Complete character
Char DB ? ; Character buffer
ExtChar DB ? ; Character buffer
COMMENTS
If DL is FFH, AL returns with the 0 flag clear and an input character from
the standard input device, if one is ready. If a character is not ready, the
0 flag will be set.
If DL is not FFH, DL is assumed to have a valid character that is output to
the standard output device. This function does not check for Ctrl-Break, or
Ctrl-PrtSc.
For function call 06H, extended ASCII codes require two function calls. The
first call returns 00H as an indicator that the next call will return an
extended code.
07H --
DIRECT CONSOLE INPUT WITHOUT ECHO
PURPOSE
Waits for a character to be read at the standard input device (unless one is
ready), then returns the character in AL.
EXAMPLE
MOV AH,07H ; Function Call -- Direct Console Input (no echo)
INT 21H ; Issue request to DOS
MOV Char,AL ; Save character
CMP AL,0 ; Extended character ?
JNE Normal Char ; No!
MOV AH,07H ; Function Call -- Direct Console Input (no echo)
INT 21H ; Issue request to DOS
MOV ExtChar,AL ; Save extended character
Normal Char:
Character LABEL WORD ; Complete character
Char DB ? ; Character buffer
ExtChar DB ? ; Character buffer
COMMENTS
As with function call 06H, no checks are made on the character.
For function call 07H, extended ASCII codes require two function calls. The
first call returns 00H as an indicator that the next call will return an
extended code.
08H --
CONSOLE INPUT WITHOUT ECHO
PURPOSE
Waits for a character to be read at the standard input device (unless one is
ready) and returns the character in AL.
EXAMPLE
MOV AH,08H ; Function Call -- Console Input (no echo)
INT 21H ; Issue request to DOS
MOV Char,AL ; Save character
CMP AL,0 ; Extended character ?
JNE Normal Char; No!
MOV AH,08H ; Function Call -- Console Input (no echo)
INT 21H ; Issue request to DOS
MOV ExtChar,AL ; Save extended character
Normal Char:
Character LABEL WORD ; Complete character
Char DB ? ; Character buffer
ExtChar DB ? ; Character buffer
COMMENTS
The character is checked for Ctrl-Break. If Ctrl-Break is detected, an
interrupt 23H is executed.
For function call 08H, extended ASCII codes require two function calls. The
first call returns 00H as an indicator that the next call will return an
extended code.
09H --
DISPLAY STRING
PURPOSE
Sends the characters in the string to the standard output device.
EXAMPLE
MOV AX,SEG String
MOV DS,AX ;Set DS:DX to string
MOV DX,OFFSET String
MOV AH,09H ;Function Call - Display String
INT 21H ;Issue request to DOS
String DB "This string ends at the first Dollar"
DB 0DH,0AH
DB "$"
COMMENTS
The character string in memory must be terminated by a $ (24H). Each
character in the string is output to the standard output device in the same
form as function call 02H.
ASCII codes 0DH and 0AH represent carriage return and line feed,
respectively.
0AH --
BUFFERED KEYBOARD INPUT
PURPOSE
Reads characters from the standard input device and places them in the buffer
beginning at the third byte.
EXAMPLE
MOV AX,SEG Buffer
MOV DS,AX ;Set DS:DX to return Buffer
MOV DX,OFFSET Buffer
MOV AH,0AH ;Function Call-Buffered
;Keyboard Input
INT 21H ;Issue request to DOS
Buffer DB 128 ; Max length of input
CurLen DB ? ; Number of characters input
; (excludes Return (0DH))
CurText DB 128 DUP(?) ; Up to 128 characters allowed
COMMENTS
The first byte of the input buffer specifies the number of characters the
buffer can hold. This value cannot be 0. Reading the standard input device
and filling the buffer continues until Enter is read. If the buffer fills to
one less than the maximum number of characters it can hold, each additional
character read is ignored and causes the bell to ring, until Enter is read.
The second byte of the buffer is set to the number of characters received,
excluding the carriage return (0DH), which is always the last character.
0BH --
CHECK STANDARD INPUT STATUS
PURPOSE
Checks if there is a character available from the standard input device.
EXAMPLE
In LOOP:
MOV AH,0BH ; Function Call -- Check Input
INT 21H ; Issue request to DOS
CMP AL,-1 ; 0FFH indicates character available
JNE In LOOP:
COMMENTS
If a character is available from the STDIN device, AL is FFH. Otherwise, AL
is undefined. If a Ctrl-Break is detected, an interrupt 23H is executed.
0CH --
CLEAR KEYBOARD BUFFER AND INVOKE A KEYBOARD FUNCTION
PURPOSE
Clears the standard input device of any characters, then executes the
function call number in AL.
EXAMPLE
MOV AH,0CH ; Function Call -- Clear keyboard &
; Invoke function
MOV AL,Function ; Function Call to execute
; (only 01H, 06H, 07H, 08H, and 0AH are allowed).
INT 21H ; Issue request to DOS
; Output depends on Function Call selected
0DH --
DISK RESET
PURPOSE
Writes to the disk file buffers that have been modified. All buffers are
then made available for reuse.
EXAMPLE
MOV AH,0DH ; Function Call -- Disk Reset
INT 21H ; Issue request to DOS
; No return
COMMENTS
It is necessary to close or commit all open files to correctly update the
disk directory.
0EH --
SELECT DISK
PURPOSE
Selects the drive specified in DL (0=A, 1=B, etc.) (if valid) as the default
drive.
EXAMPLE
MOV AH,0EH ; Function Call -- Select Disk
MOV DL,Drive ; Drive to select (0=A:, 1=B:, ...)
INT 21H ; Issue request to DOS
MOV LastDrive,AL : Save max drive number (1=A:, 2=B:, ...)
MOV AH,19H ; Function Call -- Get Current Disk
INT 21H ; Issue request to DOS
CMP AL,DL ; Selected drive = requested
JNE Error ; No, Error!
Drive DB ; New Drive to select
LastDrive DB ; Highest Valid Drive
COMMENTS
The total number of unique drive letters, including diskette and fixed disk
drives, that can be referenced is returned in AL. The value in AL is equal
to the value of LASTDRIVE in CONFIG.SYS or the total number of installed
devices, whichever is greater. For DOS 4.00 5 is the minimum value returned
in AL. If the system has only one diskette drive, it is counted as two to be
consistent with the philosophy of thinking of the system as having logical
drives A and B.
0FH --
OPEN FILE
PURPOSE
Searches the current directory for the named file and AL returns FFH if it is
not found. If the named file is found, AL returns 00H and the FCB is filled
as described below.
EXAMPLE
MOV AX,SEG FCB ;Address FCB Parameter Block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,0FH ;Function Call-FCB Open
INT 21H ;Issue request to DOS
FCB LABEL BYTE
Drive DB 0 ; Drive (0=Current, 1=A, 2=B, ...)
FName DB "FILENAME" ; File Name (blank padded)
Ext DB "EXT" ; File Extension (blank padded)
DB 25 DUP(0) ; Filled in by DOS 4.00
COMMENTS
AL is 00H if the file is opened.
AL is FFH if the file was not opened.
Use Function Call 59H (Get Extended Error) to determine the actual error
condition.
If the drive code was 0 (default drive), it is changed to the actual drive
used (1=A, 2=B, and so on). This allows changing the default drive without
interfering with subsequent operations on this file. The current block field
(FCB bytes C-D) is set to 0. The size of the record to be worked with (FCB
bytes E-F) is set to the system default of 80H. The size of the file and the
date are set in the FCB from information obtained from the directory. You
can change the default value for the
record size (FCB bytes E-F) or set the random record size and/or current
record field. Perform these actions after the open, but before any disk
operations.
The file is opened in compatibility mode. For information on compatibility
mode, refer to function call 3DH.
10H --
CLOSE FILE
PURPOSE
Closes a file.
EXAMPLE
MOV AX,SEG FCB ; Address FCB Parameter Block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,10H ; Function Call-FCB Close
INT 21H ; Issue request to DOS
CMP AL,0 ; File Closed?
JNE Error ; No, Error!
FCB LABEL BYTE
; Contents set by previous operations
COMMENTS
AL is 00H if the file is closed.
AL is FFH if the file was not closed.
Use Function Call 59H (Get Extended Error) to determine the actual error
condition.
This function call must be executed on open files after file writes, and we
highly recommend that it be used on all files. If the file is not found in
its correct position in the current directory, it is assumed the disk was
changed and AL returns FFH. Otherwise, the directory is updated to reflect
the status in the FCB, the buffers for that file are flushed, and AL returns
00H.
11H --
SEARCH FOR FIRST ENTRY
PURPOSE
Searches the current directory for the first matching filename.
EXAMPLE
MOV AX,SEG DTA ; Address Buffer for found file
MOV DS,AX ; information
MOV DX,OFFSET DTA
MOV AH,1AH ; Function Call-Set DTA address
INT 21H ; Issue request to DOS
MOV AX,SEG FCB ; Address FCB parameter block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,11H ; Function Call-FCB search first
INT 21H ; Issue request to DOS
CMP AL,0 ; File found?
JNE Error ; No, Error!
FCB LABEL BYTE
Fdrive DB 0 ; Drive (0=Current, 1=A, 2=B, ...)
Fname DB "FILENAME" ; File name (blank padded, may use ?)
Fext DB "EXT" ; File extension (blank padded, may use ?)
DB 25 DUP(0) ; Filled in by DOS
DTA LABEL BYTE
Ddrive DB ? ; Drive
Dname DB "????????" ; File Name (blank padded)
Dext DB "???" ; File Extension (blank padded)
DB 25 DUP(0) ; Filled in by DOS 4.00
COMMENTS
AL is 00H if the file is found.
AL is FFH if the file was not found.
Use Function Call 59H (Get Extended Error) to determine the actual error
condition.
The current disk directory is searched for the first matching filename. If
none are found, AL returns FFH. Global filename characters are allowed in
the filename and extension. If a matching filename is found, AL returns 00H
and the locations at the disk transfer address are set as follows:
If the FCB provided for searching was an extended FCB, the first byte at
the disk transfer address is set to FFH followed by 5 bytes of 0, then
the attribute byte from the search FCB, then the drive number used (1=A,
2=B, etc.), then the 32 bytes of the directory entry. Thus, the disk
transfer address contains a valid unopened extended FCB with the same
search attributes as the search FCB.
If the FCB provided for searching was a standard FCB, then the first byte
is set to the drive number used (1=A, 2=B), and the next 32 bytes contain
the matching directory entry. Thus, the disk transfer address contains a
valid unopened normal FCB.
NOTES:
If an extended FCB is used, the following search pattern is used:
1. If the attribute is 0, only normal file entries are found. Entries for
volume label, sub-directories, hidden and system files, are not returned.
2. If the attribute field is set for hidden or system files, or directory
entries, it is an inclusive search. All normal file entries, plus all
entries matching the specified attributes, are returned. To look at all
directory entries except the volume label, the attribute byte may be set
to hidden + system + directory (all 3 bits on).
3. If the attribute field is set for the volume label, it is considered an
exclusive search, and only the volume label entry is returned.
12H --
SEARCH FOR NEXT ENTRY
PURPOSE
Searches the current directory for the next matching filename.
EXAMPLE
MOV AX,SEG DTA ; Address Buffer for found file
MOV DS,AX ; Information
MOV DX,OFFSET DTA
MOV AH,1AH ; Function Call-Set DTA address
INT 21H ; Issue request to DOS
MOV AX,SEG FCB ; Address FCB Parameter Block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,12H ; Function Call-FCB Search Next
INT 21H ; Issue request to DOS
CMP AL,0 ; File found?
JNE Error ; No, Error!
FCB LABEL BYTE
; As set by FCB Search First
DTA LABEL BYTE
Drive DB ? ; Drive
Fname DB "????????" ; File Name (blank padded)
Ext DB "???" ; File Extension (blank padded)
DB 25 DUP(0) ; Filled in by DOS 4.00
COMMENTS
AL is 00H if the file is found.
AL is FFH if the file was not found.
Use Function Call 59H (Get Extended Error) to determine the actual error
condition.
After a matching filename has been found using function call 11H, function
12H may be called to find the next match to an ambiguous request.
The DTA contains information from the previous Search First or Search Next.
All of the FCB, except for the name/extension field, is used to keep
information necessary for continuing the search, so no disk operations may be
performed if this FCB is between a previous function 11H or 12H call and this
one.
13H --
DELETE FILE
PURPOSE
Deletes all current directory entries that match the specified filename. The
specified filename cannot be read-only.
EXAMPLE
MOV AX,SEG FCB ;Address FCB Parameter Block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,13H ;Function Call-FCB Delete File
INT 21H ;Issue request to DOS
CMP AL,0 ;File(s) Deleted?
JNE Error ;No, Error!
FCB LABEL BYTE
Drive DB 0 ; Drive
FName DB Filename ; File Name (blank padded, may
Ext DB Ext ; File Extension (blank padded, may
DB 25 DUP(0) ; Filled in by DOS
COMMENTS
AL is 00H if the file is found.
AL is FFH if the file was not found.
Use Function Call 59H (Get Extended Error) to determine the actual error
condition.
All matching current directory entries are deleted. The global filename
character "?" is allowed in the filename or extension. If no directory
entries match, AL returns FFH; otherwise AL returns 00H.
If the file is specified in read-only mode, the file is not deleted.
NOTE: Close open files before deleting them.
Network Access Rights: Requires Create access rights.
14H --
SEQUENTIAL READ
PURPOSE
Loads the record addressed by the current block (FCB bytes C-D) and the
current record (FCB byte 1F) at the disk transfer address (DTA), then the
record address is increased.
EXAMPLE
MOV AX,SEG DTA ;Address Data buffer
MOV DS,AX
MOV DX,OFFSET DTA
MOV AH,1AH ;Function call Set DTA Address
INT 21H ;Issue request to DOS
MOV AX,SEG FCB ;Address FCB Parameter Block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,14H ;Function Call-FCB Sequential Read
INT 21H ;Issue request to DOS
CMP AL,0 ;Data Read?
JNE Error ;No, Error!
FCB LABEL BYTE
; Set by previous open
DTA LABEL BYTE
DB ?Dup(0) ;I/O buffer
COMMENTS
AL is 00H if the read was successful.
AL is 01H if the file was at End of File (EOF).
AL is 02H if the read would have caused a wrap or overflow because the DTA
was too small (the read was not completed).
AL is 03H if EOF (a partial record was read and filled out with 0's).
Use Function Call 59H (Get Extended Error) to determine the actual error
condition. The length of the record is determined by the FCB record size
field.
Network Access Rights: Requires Read access rights.
15H --
SEQUENTIAL WRITE
PURPOSE
Writes the record addressed by the current block and record fields (size
determined by the FCB record size field) from the disk transfer address. If
records are less than the sector size, the record is buffered for an eventual
write when a sector's worth of data is accumulated. Then the record address
is increased.
EXAMPLE
MOV AX,SEG DTA ;Address Data buffer
MOV DS,AX
MOV DX,OFFSET DTA
MOV AH,1AH ;Function Set DTA Address
INT 21H ;Issue request to DOS
MOV AX,SEG FCB ;Address FCB Parameter Block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,15H ;Function Call-FCB Sequential Write
INT 21H ;Issue request to DOS
CMP AL,0 ;Data Written?
JNE Error ;No, Error!
FCB LABEL BYTE
; Set by previous open
DTA LABEL BYTE
DB ?Dup(0) ;I/O buffer
COMMENTS
AL is 00H if the write was successful.
AL is 01H if the disk or diskette is full (write cancelled).
AL is 02H if the write would have caused a wrap or overflow because the DTA
was too small (write cancelled).
Use Function Call 59H (Get Extended Error) to determine the actual error
condition. If the file is specified in read-only mode, the sequential write
is not performed and 01H is returned in AL.
Network Access Rights: Requires Write access rights.
16H --
CREATE FILE
PURPOSE
Creates a new file.
EXAMPLE
MOV AX,SEG FCB ;Address FCB parameter block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,16H ;Function Call-FCB create file
INT 21H ;Issue request to DOS
CMP AL,0 ;File created and opened?
JNE Error ;No, Error!
FCB LABEL BYTE
Fdrive DB 0 ; Drive (0=Current, 1=A, 2=B, ...)
Fname DB "FILENAME" ; File name (blank padded)
Fext DB "EXT" ; File extension (blank padded)
DB 25 DUP(0) ; Filled in by DOS
COMMENTS
AL is 00H if the file is created and opened.
AL is FFH if the file was not created (normally a full directory or disk
full).
Use Function Call 59H (Get Extended Error) to determine the actual error
condition.
If a matching entry is found it is reused. If no match is found, the
directory is searched for an empty entry. If a match is found, the entry is
initialized to a 0-length file, the file is opened (see function call 0FH),
and AL returns 00H.
The file may be marked hidden during its creation by using an extended FCB
containing the appropriate attribute byte.
Network Access Rights: Requires Create access rights.
17H --
RENAME FILE
PURPOSE
Changes every matching occurrence of the first filename in the current
directory of the specified drive to the second, with the restriction that two
files cannot have the same name and extension.
EXAMPLE
MOV AX,SEG FCB ;Address FCB Parameter Block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,17H ;Function Call-FCB Rename File
INT 21H ;Issue request to DOS
CMP AL,0 ;File(s) Renamed?
JNE Error ;No, Error!
FCB LABEL BYTE
Fdrive DB 0 ; Drive (0=Current, 1=A, 2=B, ...)
Fname DB "FILENAME" ; File Name (blank padded, may use ?
Fext DB "EXT" ; File Extension (blank padded, may use ?
DB 5 DUP(0) ; Reserved
NewName DB "FILENAME" ; New File Name (blank padded, may use ?
NewExt DB "EXT" ; New File Extension (blank padded, may use ?
DB 7 DUP(0) ; Reserved
COMMENTS
AL is 00H if the file or files were renamed.
AL is FFH if a file in the current directory did not match or the new name
already exists.
Use Function Call 59H (Get Extended Error) to determine the actual error
condition.
The modified FCB has a drive code and filename in the usual position, and a
second filename on the sixth byte after the first (DS:DX+11H) in what is
normally a reserved area.
If "?"s appear in the second name, the corresponding positions in the
original name are unchanged.
If the file is specified in read-only mode, the file is not renamed.
Network Access Rights: Requires Create access rights.
19H --
CURRENT DISK
PURPOSE
Determines the current default drive.
EXAMPLE
MOV AH,19H ; Function Call -- Get Current Disk
INT 21H ; Issue request to DOS
MOV Disk,AL ; Save Current Disk
Disk DB ? ; Current Disk code (0=A:, 1=B:, ...)
COMMENTS
AL returns with the code of the current default drive (0=A, 1=B, and
others.).
1AH --
SET DISK TRANSFER ADDRESS
PURPOSE
Sets the disk transfer address to DS:DX.
EXAMPLE
MOV AX,SEG DTA ;Address Buffer
MOV DS,AX
MOV DX,OFFSET DTA
MOV AH,1AH ;Function Call-Set DTA address
INT 21H ;Issue request to DOS
DTA LABEL BYTE ; Data Buffer
COMMENTS
The area defined by this call is from the address in DS:DX to the end of the
segment in DS. DOS 4.00 does not allow disk transfers to wrap around within
the segment, or overflow into the next segment. If you do not set the DTA,
the default DTA is offset 80H in the program segment prefix. To get the DTA,
issue function call 2FH.
1BH --
ALLOCATION TABLE INFORMATION
PURPOSE
Returns information about the allocation table for the default drive.
EXAMPLE
MOV AH,1BH ; Function Call -- Allocation Table
; Information
INT 21H ; Issue request to DOS
MOV NumAllocUnits,DX ; Save Number of Allocation Units
MOV NumSectsAllocUnit,AL ; Save Number of Sectors/Allocation Unit
MOV SectSize,CX ; Save of Sector Size
MOV WORD PTR MediaType@+0,BX; Save Pointer to Media Type Byte
MOV WORD PTR MediaType@+2,DS
NumAllocUnits DW ? ; Number of Allocation Units on Current
NumSectsAllocUnit DB ? ; Number Sectors in an Allocation Unit
SectSize DW ? ; Sector Size
MediaType@ DD ? ; Pointer to Media Type byte
COMMENTS
Refer to function call 36H (Get Disk Free Space).
1CH --
ALLOCATION TABLE INFORMATION FOR SPECIFIC DEVICE
PURPOSE
Returns allocation table information for a specific device.
EXAMPLE
MOV AH,1CH ; Function Call --
; Allocation Table Information
MOV DL,Drive ; Drive requested (0=current,
; 1=A:, ...)
INT 21H ; Issue request to DOS
MOV NumAllocUnits,DX ; Save Number of Allocation Units
MOV NumSectsAllocUnit,AL ; Save Number of Sectors/Allocation Unit
MOV SectSize,CX ; Save of Sector Size
MOV WORD PTR MediaType@+0,BX ; Save Pointer to Media Type Byte
MOV WORD PTR MediaType@+2,DS
Drive DB ; drive number to get info for
NumAllocUnits DW ? ; Number of Allocation Units
; on specified drive
NumSectsAllocUnit DB ? ; Number Sectors in an
; Allocation Unit
SectSize DW ? ; Sector Size
MediaType@ DD ? ; Pointer to Media Type byte
COMMENTS
This call is the same as call 1BH, except that on entry DL contains the
number of the drive that contains the needed information (0 = default, 1 = A,
and so forth.). For more information on DOS 4.00 disk allocation, refer to
"The Disk Directory" on page 2-3. Also, refer to function call 36H (Get Disk
Free Space).
21H --
RANDOM READ
PURPOSE
Reads the record addressed by the current block and current record fields
into memory at the current disk transfer address.
EXAMPLE
;Set up FCB
MOV AX,SEG DTA ;Address Data buffer
MOV DS,AX
MOV DX,OFFSET DTA
MOV AH,1AH ;Function Set DTA Address
INT 21H ;Issue request to DOS
MOV AX,SEG FCB ;Address FCB Parameter Block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,21H ;Function Call-FCB Random Read
INT 21H ;Issue request to DOS
CMP AL,0 ;Data Read?
JNE Error ;No, Error!
FCB LABEL BYTE
; Set by previous open
; DTA label byte
COMMENTS
AL is 00H if the read was successful.
AL is 01H if the file was at End of File (EOF) (no data read).
AL is 02H if the read would have caused a wrap or overflow because the DTA
was too small (the read was not completed).
AL is 03H if EOF (a partial record was read and filled out with 0's).
Use Function Call 59H (Get Extended Error) to determine the actual error
condition.
The current block and current record fields are set to agree with the random
record field. The record addressed by these fields is read into memory at
the current disk transfer address. For information on record size see
Chapter 4, "Accessing Files Using File Control Blocks" on page 4-1.
NOTE: Function 24H must be called before using this function.
Network Access Rights: Requires Read access rights.
22H --
RANDOM WRITE
PURPOSE
Writes the record addressed by the current block and current record fields
from the current disk transfer address.
EXAMPLE
;Set up FCB
MOV AX,SEG FCB ;Address FCB parameter block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,24H ;Function Call--FCB Set
;Relative record field
INT 21H ;Issue request to DOS
MOV AX,SEG DTA ;Address data buffer
MOV DS,AX
MOV DX,OFFSET DTA
MOV AH,1AH ;Function Set DTA address
INT 21H ;Issue request to DOS
MOV AX,SEG FCB ;Address FCB parameter block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,22H ;Function Call-FCB random writers
INT 21H ;Issue request to DOS
CMP AL,0 ;Data written?
JNE Error ;No, error!
FCB LABEL BYTE
; Set by previous open
DTA LABEL BYTE
COMMENTS
AL is 00H if the write was successful.
AL is 01H if the write or diskette is full (write cancelled).
AL is 02H if the read would have caused a wrap or overflow because the DTA
was too small (write cancelled).
Use Function Call 59H (Get Extended Error) to determine the actual error
condition.
The current block and current record fields are set to agree with the random
record field. Then the record addressed by these fields is written (or in
the case of records not the same as sector sizes -- buffered) from the disk
transfer address.
If the file is specified in read-only mode, the random write is not
performed.
Network Access Rights: Requires Write access rights.
23H --
FILE SIZE
PURPOSE
Searches the current directory for an entry that matches the specified file
and sets the FCBs random record field to the number of records in the file.
EXAMPLE
MOV AX,SEG FCB ; Address FCB parameter block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,23H ; Function Call-FCB file size
INT 21H ; Issue request to DOS
CMP AL,0 ; File found?
JNE Error ; No, error!
FCB LABEL BYTE
Drive DB 0 ; Drive (0=Current, 1=A, 2=B, ...)
Name DB "FILENAME" ; File name (blank padded)
Ext DB "EXT" ; File extension (blank padded)
DB 25 DUP(0) ; Filled in by DOS
COMMENTS
AL is 00H if the file exists.
AL is FFH if the file was not created (normally a full directory or disk
full).
Use Function Call 59H (Get Extended Error) to determine the actual error
condition.
The directory is searched for the matching entry. If a matching entry is
found, the random record field is set to the number of records in the file
(in terms of the record size field rounded up). If no matching entry is
found, AL returns FFH.
NOTE: If you do not set the FCB record size field before using this
function, incorrect information is returned.
24H --
SET RELATIVE RECORD FIELD
PURPOSE
Sets the random record field to the same file address as the current block
and record fields.
EXAMPLE
MOV AX,SEG FCB ;Address FCB parameter block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,24H ;Function Call--FCB set
;Relative record field
INT 21H ;Issue request to DOS
FCB LABEL BYTE
; Set by previous open
COMMENTS
You must call this function before you perform random reads and writes, and
random block reads and writes.
25H --
SET INTERRUPT VECTOR
PURPOSE
Sets the interrupt vector table for the interrupt number.
EXAMPLE
MOV AX,SEG Handler ;Address new handler
MOV DS,AX
MOV DX,OFFSET Handler
MOV AH,25H ;Function Call - Set Interrupt
;Vector
MOV AL,Vector
INT 21H ;Issue request to DOS
Vector DB ? ;Number of vector to be replaced
Handler: ;Code to process interrupt
COMMENTS
The interrupt vector table for the interrupt number specified in AL is set to
address contained in DS:DX. Use function call 35H (Get Interrupt Vector) to
obtain the contents of the interrupt vector.
26H --
CREATE NEW PROGRAM SEGMENT
PURPOSE
Creates a new program segment.
EXAMPLE
MOV AH,26H ; Function Call -- Create Program
; Segment
MOV DX,SEG PSP ; Segment address to create new PSP
INT 21H ; Issue request to DOS
PSP LABEL BYTE ; Area to fill in
DB 100H DUP(0)
COMMENTS
The entire 100H area at location 0 in the current program segment is copied
into location 0 in the new program segment. The memory size information at
location 6 in the new segment is updated and the current termination,
Ctrl-Break exit and critical error addresses from interrupt vector table
entries for interrupts 22H, 23H, and 24H are saved in the new program segment
starting at 0AH. They are restored from this area when the program ends.
NOTE: The EXEC function call 4BH provides a more complete service.
Therefore, you should use the EXEC 4BH and avoid using this call.
27H --
RANDOM BLOCK READ
PURPOSE
Reads the specified number of records (in terms of the record size field)
from the file address specified by the random record field into the disk
transfer address.
EXAMPLE
;Set up disk transfer address
MOV AX,SEG DTA ;Address data buffer
MOV DS,AX
MOV DX,OFFSET DTA
MOV AH,1AH ;Function set DTA address
INT 21H ;Issue request to DOS
MOV AX,SEG FCB ;Address FCB parameter block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,24H ;Function Call -- FCB Set
;Relative Record Field
INT 21H ;Issue request to DOS
MOV AX,SEG FCB ;Address FCB parameter block
MOV DS,AX
MOV DX,OFFSET FCB
MOV CX,Records to read ;number of records to read
MOV AH,27H ;Function Call - FCB random block read
INT 21H ;Issue request to DOS
CMP AL,0 ;Data read?
JNE Error ;No, error!
FCB LABEL BYTE
; Set by previous open
DTA LABEL BYTE
DB ?Dup(0) ;I/O buffer
Records to read DW ?
COMMENTS
AL is 00H if the read was successful.
AL is 01H if the file was at End of File (EOF) (no data read).
AL is 02H if the read would have caused a wrap or overflow because the DTA
was too small (the read was not completed.).
AL is 03H if EOF (a partial record was read and filled out with zeros).
Use Function Call 59H (Get Extended Error) to determine the actual error
condition.
The random record field and the current block/record fields are set to
address the next record (the first record not read).
NOTE: Function 24H must be called before using this function.
Network Access Rights: Requires Read access rights.
28H --
RANDOM BLOCK WRITE
PURPOSE
Writes the specified number of records from the disk transfer address into
the file address specified by the random record field.
EXAMPLE
;Set up disk transfer address
MOV AX,SEG DTA ;Address data buffer
MOV DS,AX
MOV DX,OFFSET DTA
MOV AH,1AH ;Function set DTA address
INT 21H ;Issue request to DOS
MOV AX,SEG FCB ;Address FCB parameter block
MOV DS,AX
MOV DX,OFFSET FCB
MOV AH,24H ;Function Call--FCB set
;Relative record field
INT 21H ;Issue request to DOS
MOV AX,SEG FCB ;Address FCB parameter block
MOV DS,AX
MOV DX,OFFSET FCB
MOV CX,Records to write ;Number of records to write
MOV AH,28H ;Function Call - FCB Random Block write
INT 21H ;Issue request to DOS
CMP AL,0 ;Data written?
JNE Error ;No, error!
DTA LABEL BYTE
DB ?DUP(0) ; I/O Buffer
COMMENTS
AL is 00H if the write was successful.
AL is 01H if the disk or diskette is full (write cancelled).
AL is 02H if the write would have caused a wrap or overflow because the DTA
was too small (write cancelled).
Use Function Call 59H (Get Extended Error) to determine the actual error
condition.
If there is insufficient space on the disk, AL returns 01H and no records are
written. If CX is 0 upon entry, no records are written, but the file is set
to the length specified by the random record field, whether longer or shorter
than the current file size. (Allocation units are released or allocated as
appropriate.)
NOTE: Function call 24H must be called before using this function.
Network Access Rights: Requires Write access rights.
29H --
PARSE FILENAME
PURPOSE
Parses the specified filename.
EXAMPLE
MOV AX,SEG CmdBuf
MOV DS,AX ;Address command string
MOV SI,OFFSET CmdBuf
MOV AX,SEG FCB
MOV ES,AX ;Address FCB Parameter Block
MOV DI,OFFSET FCB
MOV AH,29H ;Function Call - FCB Parse Filename
MOV AL,OPTIONS ;Set desired action
INT 21H ;Issue request to DOS
CMP AL,-1 ;Drive valid?
JE Error ;No, Error!
CmdBuf LABEL BYTE
DB " a:file.ext ",0DH
FCB LABEL BYTE
; Created in a pre-open state based on input found.
Options DB ? ;parsing options
COMMENTS
The contents of AL are used to determine the action to take, as shown below:
<must = 0>
bit: 7 6 5 4 3 2 1 0
If bit 0 = 1, leading separators are scanned off the command line at DS:SI.
Otherwise, no scan-off of leading separators takes place.
If bit 1 = 1, the drive ID byte in the FCB will be set (changed) only if a
drive was specified in the command line being parsed.
If bit 2 = 1, the filename in the FCB will be changed only if the command
line contains a filename.
If bit 3 = 1, the filename extension in the FCB will be changed only if the
command line contains a filename extension.
Filename separators include the following characters:
: . : , = + along with TAB and SPACE. Filename terminators include all of
these characters plus ,<, >, |, /, ', [, ], and any control characters.
Output:
AL is 00H if no global characters (? or *) were found in the Command String.
AL is 01H if global characters (? or *) were found in the Command String.
AL is FFH if the drive specified is invalid.
The command line is parsed for a filename of the form d:filename.ext, and if
found, a corresponding unopened FCB is created at ES:DI. If no drive
specifier is present, it is assumed to be all blanks. If the character *
appears in the filename or extension, it and all remaining characters in the
name or extension are set to ?.
DS:SI returns pointing to the first character after the filename and ES:DI
points to the first byte of the formatted FCB. If no valid filename is
present, ES:DI+1 contains a blank.
2AH --
GET DATE
PURPOSE
Returns the day of the week, the year, month and date.
EXAMPLE
MOV AH,2AH ; Function Call -- Get Date
INT 21H ; Issue request to DOS
MOV DayofWeek,AL ; Save Day of the Week
MOV Year,CX ; Save Year
MOV Month,DH ; Save Month
MOV Day,DL ; Save Day
DayofWeek DB ? ; 0=Sunday, ... 6=Saturday
Year DW ? ; 1980 to 2099
Month DB ? ; 1 to 12
Day DB ? ; 1 to 31
COMMENTS
If the time-of-day clock rolls over to the next day, the date is adjusted
accordingly, taking into account the number of days in each month and leap
years.
2BH --
SET DATE
PURPOSE
Sets the date (also sets CMOS clock, if present).
EXAMPLE
MOV AH,2BH ; Function Call -- Set Date
MOV CX,Year ; Set Year
MOV DH,Month ; Set Month
MOV DL,Day ; Set Day
INT 21H ; Issue request to DOS
CMP AL,0 ; Valid Date?
JNE Error ; No!
Year DW ? ; 1980 to 2099
Month DB ? ; 1 to 12
Day DB ? ; 1 to 31
COMMENTS
AL is 00H if the date is valid and the operation is successful.
AL is FFH if the date is not valid.
On entry, CX:DX must have a valid date in the same format as returned by
function call 2AH.
On return, AL returns 00H if the date is valid and the set operation is
successful. AL returns FFH if the date is not valid.
2CH --
GET TIME
PURPOSE
Returns the time; hours, minutes, seconds and hundredths of seconds.
EXAMPLE
MOV AH,2CH ; Function Call --
; Get Time
INT 21H ; Issue request to DOS
MOV Hour,CH ; Save Hour
MOV Minute,CL ; Save Minute
MOV Second,DH ; Save Second
MOV Hundredth,DL ; Save Partial Second
Hour DB ? ; 0 to 23
Minute DB ? ; 0 to 59
Second DB ? ; 0 to 59
Hundredth DB ? ; 0 to 99
COMMENTS
On entry, AH contains 2CH. On return, CX:DX contains the time-of-day. Time
is actually represented as four 8-bit binary quantities as follows:
CH Hours (0-23)
CL Minutes (0-59)
DH Seconds (0-59)
DL 1/100 seconds (0-99).
This format is readily converted to a printable form yet can also be used for
calculations, such as subtracting one time value from another.
2DH --
SET TIME
PURPOSE
Sets the time (also sets the CMOS clock, if present).
EXAMPLE
MOV AH,2DH ; Function Call -- Set Time
MOV CH,Hour ; Sst Hour
MOV CL,Minute ; Set Minute
MOV DH,Second ; Set Second
MOV DL,Hundredth ; Set Partial Second
INT 21H ; Issue request to DOS
CMP AL,0 ; Valid Time?
JNE Error ; No!
Hour DB ? ; 0 to 23
Minute DB ? ; 0 to 59
Second DB ? ; 0 to 59
Hundredth DB ? ; 0 to 99
COMMENTS
AL is 00H if the time is valid.
AL is FFH if the time is not valid.
On entry, CX:DX has time in the same format as returned by function 2CH. On
return, if any component of the time is not valid, the set operation is
cancelled and AL returns FFH. If the time is valid, AL returns 00H.
If your system has a CMOS realtime clock, it will be set.
2EH --
SET/RESET VERIFY SWITCH
PURPOSE
Sets the verify switch.
EXAMPLE
; To set VERIFY=OFF
MOV AH,2EH ; Function Call -- Set
; VERIFY
MOV AL,0 ; Set OFF
INT 21H ; Issue request to DOS
; To set VERIFY=ON
MOV AH,2EH ; Function Call -- Set
; VERIFY
MOV AL,1 ; Set ON
INT 21H ; Issue request to DOS
COMMENTS
On entry, AL must contain 01H to turn verify on, or 00H to turn verify off.
When verify is on, DOS 4.00 performs a verify operation each time it performs
a disk write to assure proper data recording. Although disk recording errors
are very rare, this function has been provided for applications in which you
may wish to verify the proper recording of critical data. You can obtain the
current setting of the verify switch through function call 54H.
NOTE: Verification is not supported on data written to a network disk.
2FH --
GET DISK TRANSFER ADDRESS (DTA)
PURPOSE
Returns the current disk transfer address.
EXAMPLE
MOV AH,2FH ; Function Call -- Get
; DTA Address
INT 21H ; Issue request to DOS
MOV WORD PTR DTA@+0,BX ; Save Address
MOV WORD PTR DTA@+2,ES
DTA@ DD ? ; DTA Buffer
COMMENTS
On entry, AH contains 2FH. On return, ES:BX contains the current Disk
Transfer Address. You can set the DTA using function call 1AH.
30H --
GET DOS VERSION NUMBER
PURPOSE
Returns the DOS version number.
EXAMPLE
PUSH CX ; CX and BX destroyed in call
PUSH BX
MOV AH,30H ; Function Call -- Get DOS 4.00
; Version
INT 21H ; Issue request to DOS
MOV MajorVersion,AL ; Save Version
MOV MinorVersion,AH
POP BX
POP CX
MajorVersion DB ? ; X of X.YY
MinorVersion DB ? ; YY of X.YY
COMMENTS
On entry, AH contains 30H. On return, BX and CX are set to 0. AL contains
the major version number. AH contains the minor version number.
If AL returns a major version number of 0, you can assume that the DOS
version is pre-DOS 2.00.
31H --
TERMINATE PROCESS AND REMAIN RESIDENT
PURPOSE
Terminates the current process and attempts to set the initial allocation
block to the memory size in paragraphs.
EXAMPLE
MOV AH,31H ; Function Call -- Terminate
; and Keep Process
MOV AL,RetCode ; Set value of ERRORLEVEL
MOV DX,MySize ; Set my program and data size
INT 21H ; Issue request to DOS
INT 20H ; Be safe if on DOS 4.00 Version 1.X
RetCode DB ? ; Value to return to my EXEC'er
MySize DW ? ; Size of my code and data
; (in paragraphs)
COMMENTS
On entry, AL contains a binary return code. DX contains the memory size
value in paragraphs. This function call does not free up any other
allocation blocks belonging to that process. Files opened by the process are
not closed when the call is executed. The return code passed in AL is
retrievable by the parent through Wait (function call 4DH) and can be tested
through the ERRORLEVEL batch subcommands.
Memory is used efficiently if the block containing a copy of the environment
is deallocated before terminating. This can be done by loading ES with the
segment contained in 2C of the PSP, and issuing function call 49H (Free
Allocated Memory). The five standard handles, 0000 through 0004, should be
closed before exiting.
33H --
GET/SET SYSTEM VALUE
PURPOSE
Set or get the state of System Values such as BREAK (Ctrl-Break checking).
EXAMPLE
; To check BREAK state
MOV AH,33H ; Function Call -- Get/Set
; System value
MOV AL,0 ; Do Get BREAK
INT 21H ; Issue request to DOS
MOV BREAK,DL ; Save state
; To set BREAK=OFF
MOV AH,33H ; Function Call -- Get/Set
; System value
MOV AL,1 ; Do Set BREAK
MOV DL,0 ; Set OFF
INT 21H ; Issue request to DOS
; To set BREAK=ON
MOV AH,33H ; Function Call -- Get/Set
; System Value
MOV AL,1 ; Do Set BREAK
MOV DL,1 ; Set ON
INT 21H ; Issue request to DOS
; To get the Boot Drive
MOV AH,33H ; Function Call -- Get/Set
; System Value
MOV AL,5 ; Do Get Boot Drive
INT 21H ; Issue request to DOS
MOV Drive,DL ; Save boot drive
BREAK DB ? ; Current BREAK state (0=OFF, 1=ON)
Drive DB ? ; DOS 4.00 boot drive
COMMENTS
For BREAK:
AL contains 00H to request the current state of Ctrl-Break checking. On
return DL contains the current state (00H = OFF, 01H = ON).
AL contains 01H to set the state. DL contains the new state (00H = OFF, 01H
= ON).
For boot drive:
AL contains 05H to request the boot drive. On return DL contains the drive
(A:=1, C:=3, ...).
35H --
GET INTERRUPT VECTOR
PURPOSE
To obtain the address in an interrupt vector.
EXAMPLE
MOV AH,35H ; Function Call --
; Set Interrupt Vector
MOV AL,Vector ; Vector to get (0 to 255)
INT 21H ; Issue request to DOS
MOV WORD PTR OldVect+0,BX
MOV WORD PTR OldVect+2,ES
OldVect DD ? ; Previous vector contents
Vector DB ? ; Vector number to get
COMMENTS
On entry, AH contains 35H. AL contains a hexadecimal interrupt number. On
return, ES:BX contains the CS:IP interrupt vector for the specified
interrupt. Use function call 25H (Set Interrupt Vector) to set the interrupt
vectors.
36H --
GET DISK FREE SPACE
PURPOSE
Returns the disk free space (available clusters, clusters/drive,
bytes/sector).
EXAMPLE
MOV AH,36H ; Function Call --
; Get disk free space
MOV DL,Drive ; Drive to query
; (0=current, 1=A:,
; 2=B:, ...)
INT 21H ; Issue request to DOS
CMP AX,-1 ; Error?
JE Error ; Yes
MOV SectAU,AX ; Save allocation unit
; Size
MOV AvailAU,BX ; Save free allocation
; Units
MOV SectSize,CX ; Save sector size
MOV TotalAU,DX ; Save disk size
MOV AX,SectSize ; Calculate allocation
; Unit size
MUL SectAU
MOV CX,AX ; CX = bytes/AU
MOV AX,TotalAU ; Calculate total space
MUL CX
MOV WORD PTR TotalBytes+0,AX ; Save it
MOV WORD PTR TotalBytes+2,DX
MOV AX,AvailAU ; Calculate free space
MUL CX
MOV WORD PTR FreeBytes+0,AX ; Save it
MOV WORD PTR FreeBytes+2,DX
SectAU DW ? ; Sectors in an
; Allocation unit
AvailAU DW ? ; Free allocation units
SectSize DW ? ; Bytes in a sector
TotalAU DW ? ; Number of allocation
; Units on DL disk
TotalBytes DD ? ; Disk size in bytes
FreeBytes DD ? ; Free space in bytes
Drive DD ? ; Drive number to get info for
COMMENTS
If the drive number in DL was valid, BX contains the number of available
allocation units, DX contains the total number of allocation units on the
drive, CX contains the number of bytes per sector, and AX contains the number
of sectors for each allocation unit.
38H --
GET OR SET COUNTRY DEPENDENT INFORMATION
PURPOSE
Sets the Active Country or returns country dependent information.
EXAMPLE
; To set the Current Country
MOV AH,38H ; Function Call -- Get/Set
; Country Information
MOV AL,CountryID ; Country ID (-1 if >= 255)
MOV BX,CountryIDX ; Country ID (if AL=-1)
MOV DX,-1 ; Indicate set country code
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
; To get Country Information
MOV AX,SEG Buffer
MOV DS,AX
MOV DX,OFFSET Buffer
MOV AH,38H
MOV AL,CountryID ; Country ID (-1 if >= 255)
; (0 to get current country)
MOV BX,CountryIDX ; Country ID (if AL=-1)
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV CountryCode,BX ; Save current Country Code
CountryCode DW ? ; Current country code
CountryIDX DW ? ; Extended country code for input
Buffer LABEL WORD ; Country information (see format below)
CountryID DB ? ; Country code for input
COUNTRY INFORMATION
DateFormat DW ? ; Date Format:
; 0 = m d y order
; 1 = d m y order
; 2 = y m d order
$Symbol DB "????",0 ; Currency Symbol
; example: "DM",0,?,?
Sep1000 DB "?",0 ; Thousands Separator
; example: ",",0
Sep1 DB "?",0 ; Fractions Separator
; example: ".",0
SepDate DB "?",0 ; Date Separator
; example: "/",0
SepTime DB "?",0 ; Time Separator
; example: ":",0
$Format DB ? ; Currency Format:
; 0 = currency symbol, value
; 1 = value, currency symbol
; 2 = currency symbol, space, value
; 3 = value, space, currency symbol
; 4 = currency symbol is decimal separat
SigDigits DB ? ; Number of Significant Digits in Currency
TimeFormat DB ? ; Time Format:
; 0 = 12 hour clock
; 1 = 24 hour clock
UpperCaseAL@ DD ? ; Address of Routine to Upper Case AL
; Only for values >=80H
SepData DB "?",0 ; Data List Separator
; example: ",",0
Reserved DW 5 DUP(?) ; Reserved for future
COMMENTS
The date format has the following values and meaning:
CODE DATE
0=USA m d y
1=EUROPE d m y
2=JAPAN y m d
Case Map Call Address: The register contents for the case map call are:
+---------------------------------------------------------------------------+
| ON REGISTER |
| ENTRY CONTENTS |
+---------------------------------------------------------------------------+
| AL ASCII code of character to be converted to uppercase |
+---------------------------------------------------------------------------+
+---------------------------------------------------------------------------+
| ON REGISTER |
| RETURN CONTENTS |
+---------------------------------------------------------------------------+
| AL ASCII code of the uppercase input character |
+---------------------------------------------------------------------------+
The case map call address is in a form suitable for a FAR call indirect.
RETURNS
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location. Function Call 65H, (Get Extended Country Information), returns
more country information and is preferred.
Setting the Current County Code by using this function call is not
recommended. The user can set it by placing a COUNTRY command in the
CONFIG.SYS file. The Country Code set by the user should not be changed.
The NLSFUNC DOS 4.00 extension must be installed to change the Current
Country.
39H --
CREATE SUBDIRECTORY (MKDIR)
PURPOSE
Creates the specified directory.
EXAMPLE
MOV AX,SEG DName ;Directory Name
MOV DS,AX
MOV DX,OFFSET DName
MOV AH,39H ;Function-Make a directory
INT 21H ;Issue request to DOS
JC Error
DName DB "?? .. ??",0 ; ASCIIZ Name
; Example:
; "c:\dir",0
COMMENTS
On entry, DS:DX contains the address of an ASCIIZ string with drive and
directory path names. All directory levels other than the last one in the
name must exist before using this function. Only one directory level at a
time can be created with this function. The maximum length of the ASCIIZ
string is 64 characters.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
Network Access Rights: Requires Create access rights.
3AH --
REMOVE SUBDIRECTORY (RMDIR)
PURPOSE
Removes the specified directory.
EXAMPLE
MOV AX,SEG DName ;Directory name
MOV DS,AX
MOV DX,OFFSET DName
MOV AH,3AH ;Function-Remove directory
INT 21H ;Issue request to DOS
JC Error
DName DB "?? .. ??",0 ; ASCIIZ Name
; example: "c:\dir",0
COMMENTS
On entry, DS:DX contains the address of an ASCIIZ string with the drive and
directory path names. The specified directory is removed from the structure.
The current directory or a directory with files in it cannot be removed.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
Network Access Rights: Requires Create access rights.
3BH --
CHANGE THE CURRENT DIRECTORY (CHDIR)
PURPOSE
Changes the current directory to the specified directory.
EXAMPLE
MOV AX,SEG DName ;Directory name
MOV DS,AX
MOV DX,OFFSET DName
MOV AH,3BH ;Function -- Change directory
INT 21H ;Issue request to DOS
JC Error
DName DB "?? .. ??",0 ; ASCIIZ Name
; example: "c:\dir",0
COMMENTS
On entry, DS:DX contains the address of an ASCIIZ string with drive and
directory path names. The string is limited to 64 characters and cannot
contain a network path. If any member of the directory path does not exist,
the directory path is not changed. Otherwise, the current directory is set
to the ASCIIZ string.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
3CH --
CREATE A FILE (CREAT)
PURPOSE
Creates a new file or shortens an old file to 0 length in preparation for
writing.
EXAMPLE
MOV AX,SEG FName ;File name
MOV DS,AX
MOV DX,OFFSET FName
MOV AH,3CH ;Function -- Create a File
MOV CX,Attribute ; Attribute of the file
; Allowed values
; 0001H=Read only
; 0002H=Hidden
; 0004H=System
; 0008H=Volume label
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV Handle,AX ; Save file handle for
FName DB "?? .. ??",0 ; ASCIIZ Name
; example: "c:\dir\file.ext",0
Handle DW ? ; File handle
Attribute DW ? ; Attributes for directory entry
COMMENTS
If the file did not exist, the file is created in the appropriate directory
and the file is given the read/write access code. The file is opened for
read/write, the read/write pointer is set to the first byte of the file and
the handle is returned in AX. Note that function call 43H (Change File Mode)
can be used later to change the file's attribute.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
This function does not replace an existing volume label. You must delete the
existing volume label before issuing this call.
Network Access Rights: Requires Create access rights.
3DH --
OPEN A FILE
PURPOSE
Opens the specified file.
EXAMPLE
MOV AX,SEG FName ; File name
MOV DS,AX
MOV DX,OFFSET FName
MOV AH,3DH ; Function -- Open a File
MOV AL,OpenMode
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV Handle,AX ; Save file handle for following operations
FName DB "?? .. ??",0 ; ASCIIZ Name
; example: "c:\dir\file.ext",0
Handle DW ? ; File Handle
OpenMode DB ? ; Open mode
COMMENTS
The read/write pointer is set at the first byte of the file and the record
size of the file is 1 byte. The read/write pointer can be changed with
function call 42H. The returned file handle must be used for subsequent
input and output to the file. The file's date and time can be obtained or
set through call 57H, and its attribute can be obtained through call 43H.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
NOTES:
1. This call opens any normal or hidden file whose name matches the name
specified.
2. Device names cannot end in a colon.
3. When a file is closed, any sharing restrictions placed on it by the open
are canceled.
4. File sharing must be loaded, or the file must be a network file for the
sharing modes to function. Refer to the SHARE command.
5. The file read-only attribute can be set when creating the file using
extended FCBs or specifying the appropriate attribute in CX and using the
CHMOD interrupt 21H function call or the DOS 4.00 ATTRIB command.
6. If the file is inherited by the subordinate process, all sharing and
access restrictions are also inherited.
7. If an open file handle is duplicated by either of the DUP function calls,
all sharing and access restrictions are also duplicated.
OPEN MODE
The open mode is defined in AL and consists of four bit-oriented fields:
INHERITANCE FLAG Specifies if the opened file is inherited by a
subordinate process.
SHARING MODE FIELD Defines which operations other processes can perform on
the file.
RESERVED FIELD
ACCESS FIELD Defines which operations the current process can perform
on the file.
BIT FIELDS
The bit fields are mapped as follows:
<I> < S > <R> < A >
Open Mode bits 7 6 5 4 3 2 1 0
I Inheritance flag
If I = 0; File is inherited by subordinate processes.
If I = 1; File is private to the current process.
S Sharing Mode
The file is opened as follows:
S = 000 -- Compatibility mode
S = 001 -- DenyRead/Write mode (exclusive)
S = 010 -- DenyWrite mode
S = 011 -- DenyRead mode
S = 100 -- DenyNone mode
Any other combinations are invalid.
When opening a file, you must inform DOS 4.00 which operations any
other processes, in sharing mode, can perform on the file.
The default, compatibility mode, denies all other computers in a
network access to the file. If other processes can continue to read
the file while your process is operating on it, specify DenyWrite.
DenyWrite prohibits writing by other processes, but allows reading.
Similarly, you must specify which operations, or access modes, your
process can perform. The default access mode, ReadWrite, causes the
open request to fail if another process on the computer or any other
computer on a network has the file opened with any sharing mode other
than DenyNone. If you intend to read from the file only, your Open
will succeed unless all other processes have specified DenyNone or
DenyWrite. File sharing requires cooperation of both sharing
processes.
R Reserved (set this bit field to 0).
A Access
The file access is assigned as follows:
If A = 000; Read access
If A = 001; Write access
If A = 010; Read/Write access
Any other combinations are invalid.
Network Access Rights: If the Access field (A) of the Open mode field (AL)
is equal to:
000 Requires Read access rights
001 Requires Write access rights
010 Requires Read/Write access rights
COMPATIBILITY MODE
A file is considered to be in compatibility mode if the file is opened by:
Any of the CREATE function calls
An FCB function call
A handle function call with compatibility mode specified.
A file can be opened any number of times in compatibility mode by a single
process, provided that the file is not currently open under one of the other
four sharing modes. If the file is marked read-only, and is open in
DenyWrite sharing mode with Read Access, the file may be opened in
Compatibility Mode with Read Access. If the file was successfully opened in
one of the other sharing modes and an attempt is made to open the file again
in Compatibility Mode, an interrupt 24H is generated to signal this error.
The base interrupt 24H error indicates DRIVE NOT READY, and the extended
error indicates a SHARING VIOLATION.
SHARING MODES
The sharing modes for a file opened in compatibility mode are changed by DOS
4.00 depending on the read-only attribute of the file. This allows sharing
of read-only files.
+---------------------------------------------------+
| READ-ONLY |
| FILE OPENED BY ACCESS SHARING MODE |
+---------------------------------------------------+
| FCB Read-Only DenyWrite |
+---------------------------------------------------+
| Handle Read Read-Only DenyWrite |
+---------------------------------------------------+
| Handle Write Error ----- |
+---------------------------------------------------+
| Handle Error ----- |
| Read/Write |
+---------------------------------------------------+
+---------------------------------------------------+
| NOT READ-ONLY |
| FILE OPENED BY ACCESS SHARING MODE |
+---------------------------------------------------+
| FCB Read/Write Compatibility |
+---------------------------------------------------+
| Handle Read Read Compatibility |
+---------------------------------------------------+
| Handle Write Write Compatibility |
+---------------------------------------------------+
| Handle Read/Write Compatibility |
| Read/Write |
+---------------------------------------------------+
DENYREAD/WRITE MODE (EXCLUSIVE)
If a file is successfully opened in DenyRead/Write mode, access to the file
is exclusive. A file currently open in this mode cannot be opened again in
any sharing mode by any process (including the current process) until the
file is closed.
DENYWRITE MODE
A file successfully opened in DenyWrite sharing mode, prevents any other
write access opens to the file (A = 001 or 010) until the file is closed. An
attempt to open a file in DenyWrite mode is unsuccessful if the file is open
with a write access.
DENYREAD MODE
A file successfully opened in DenyRead sharing mode, prevents any other read
sharing access opens to the file (A = 000 or 010) until the file is closed.
An attempt to open a file in DenyRead sharing mode is unsuccessful if the
file is open in Compatibility mode or with a read access.
DENYNONE MODE
A file successfully opened in DenyNone mode, places no restrictions on the
read/write accessibility of the file. An attempt to open a file in DenyNone
mode is unsuccessful if the file is open in Compatibility mode.
When accessing files that reside on a network disk, no local buffering is
done when files are opened in any of the following sharing modes:
DenyRead
DenyNone.
Therefore, in a network environment, DenyRead/Write sharing mode,
Compatibility sharing mode, and DenyWrite mode opens are buffered locally.
The following sharing matrix shows the results of opening, and subsequently
attempting to reopen the same file using all combinations of access and
sharing modes:
Y :2nd,3rd,...open is allowed
N :2nd,3rd,...open is denied
DRW :DenyRead/Write Mode (Exclusive)
DW :DenyWrite Mode
DR :DenyRead Mode
ALL :Read/Write Mode
I :Read Only Access
O :Write Only Access
IO :Read/Write Access
3EH --
CLOSE A FILE HANDLE
PURPOSE
Closes the specified file handle.
EXAMPLE
MOV AH,3EH ; Function Call --
; Close a Handle
MOV BX,Handle
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
Handle DW ? ; File Handle (from Open / Create)
COMMENTS
On entry, BX contains the file handle that was returned by Open or Create.
On return, the file is closed, the directory is updated, and all internal
buffers for that file are flushed.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
3FH --
READ FROM A FILE OR DEVICE
PURPOSE
Transfers the specified number of bytes from a file into a buffer location.
EXAMPLE
MOV AX,SEG Buffer ; Address data buffer
MOV DS,AX
MOV DX,OFFSET Buffer
MOV AH,3FH ; Function -- Read from a file
MOV BX,Handle
MOV CX,BufSize ; Buffer size
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
CMP AX,0 ; At End Of File?
JE EOF ; Yes!
MOV SizeRead,AX ; Save Amount Read
N EQU 512 ; Typical buffer size
Handle DW ? ; File Handle (from Open /Create)
BufSize DW N ; Buffer Size, N is
Buffer DB N DUP(?) ; Data Buffer
SizeRead DW ? ; Amount of Data in Buffer
COMMENTS
On entry, BX contains the file handle. CX contains the number of bytes to
read. DS:DX contains the buffer address. On return, AX contains the number
of bytes read.
This function call attempts to transfer (CX) bytes from a file into a buffer
location. It is not guaranteed that all bytes will be read. For example,
when DOS 4.00 reads from the keyboard, at most one line of text is
transferred. If this read is performed from the standard input device, the
input can be redirected. If the value in AX is 0, then the program has tried
to read from the end of file.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
Network Access Rights: Requires Read access rights.
40H --
WRITE TO A FILE OR DEVICE
PURPOSE
Transfers the specified number of bytes from a buffer into a specified file.
EXAMPLE
MOV AX,SEG Buffer ;Data Buffer
MOV DS,AX
MOV DX,OFFSET Buffer
MOV CX,BufSize
MOV AH,40H ;Function-Write to a File
MOV BX,Handle
MOV DX,OFFSET Buffer
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
CMP AX,CX ; Disk Full?
JB FullDisk ; Yes!
N EQU 512 ; Typical buffer size
Handle DW ? ; File Handle (from Open / Create)
BufSize DW N ; Buffer Size
Buffer DB N DUP(?) ; Data Buffer
COMMENTS
On entry, BX contains the file handle. CX contains the number of bytes to
write. DS:DX contains the address of the data to write.
This function call attempts to transfer (CX) bytes from a buffer into a file.
AX returns the number of bytes actually written. If the carry flag is not
set and this value is not the same as the number requested (in CX), it should
be considered an error. Although no error code is returned, your program can
compare these values. Normally, the reason for the error is a full disk. If
this write is performed to the standard output device, the output can be
redirected.
To truncate a file at the current position of the file pointer, set the
number of bytes (CX) to 0 before issuing the interrupt 21H. The file pointer
can be moved to the desired position by reading, writing, and performing
function call 42H, (Move File Read/Write Pointer.)
If the file is read-only, the write to the file or device is not performed.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
Network Access Rights: Requires Write access rights.
41H --
DELETE A FILE FROM A SPECIFIED DIRECTORY (UNLINK)
PURPOSE
Removes a directory entry associated with a filename.
EXAMPLE
MOV AX,SEG FName ; File Name
MOV DS,AX
MOV DX,OFFSET FName
MOV AH,41H ; Function-Delete a File
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
FName DB "?? .. ??",0 ; ASCIIZ Name
; example: "c:\dir\File.ext",0
COMMENTS
Global filename characters are not allowed in any part of the ASCIIZ string.
Read-only files cannot be deleted by this call. To delete a read-only file,
you can first use call 43H to change the file's read-only attribute to 0,
then delete the file.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
Network Access Rights: Requires Create access rights.
42H --
MOVE FILE READ WRITE POINTER (LSEEK)
PURPOSE
Moves the read/write pointer according to the method specified.
EXAMPLE
MOV AH,42H ; Function Call --
; Move Read/Write Pointer
MOV AL,Method ; Method of Positioning:
; 0 = From Beginning of File
; (BOF)
; 1 = From Current Position
; 2 = From End of File (EOF)
MOV BX,Handle ; Select File
MOV DX,WORD PTR Position+0 ; New Position = Position + METHOD
MOV CX,WORD PTR Position+2
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV WORD PTR Position+0,AX ; Set new File Position
MOV WORD PTR Position+2,DX
Handle DW ? ; File Handle (from Open /
; Create)
Position DD ? ; File Offset (may be
; negative)
Method DB ?
COMMENTS
On entry, AL contains a method value. BX contains the file handle. CX:DX
contains the desired offset in bytes with CX containing the most significant
part. On return, DX:AX contains the new location of the pointer with DX
containing the most significant part if the carry flag is not set.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
This function call moves the read/write pointer according to the following
methods:
+---------+-----------------------------------------------------------------+
| AL | DESCRIPTION |
+---------+-----------------------------------------------------------------+
| 0 | The pointer is moved CX:DX bytes (offset) from the beginning of |
| | the file. |
+---------+-----------------------------------------------------------------+
| 1 | The pointer is moved to the current location plus offset. |
+---------+-----------------------------------------------------------------+
| 2 | The pointer is moved to the end-of-file plus offset. This |
| | method can be used to determine file's size. |
+---------+-----------------------------------------------------------------+
NOTE: If an LSEEK operation is performed on a file that resides on a network
disk that is open in either DenyRead or DenyNone sharing mode, the
read/write pointer information is adjusted on the computer where the
file actually exists. If the file is opened in any other sharing
mode, the read/write pointer information is kept on the remote
computer.
43H --
CHANGE FILE MODE (CHMOD)
PURPOSE
Changes the file mode of the specified file.
EXAMPLE
; To Get Attributes
MOV AX,SEG FName ;File Name
MOV DS,AX
MOV DX,OFFSET FName ;DS:DX points to ASCIIZ path name
MOV AL,0 ;Indicate get
MOV AH,43H ;Function-Change File Mode
INT 21H ;Issue request to DOS
JC Error ;Error code in AX
MOV Attribute,CX ;Save Attribute
; To Set Attributes
MOV AX,SEG FName ;File Name
MOV DS,AX
MOV DX,OFFSET FName ;DS:DX points to ASCIIZ path name
MOV AL,1 ;Indicate set
MOV AH,43H ;Function-Change File Mode
MOV CX,Attribute ;Set Attribute
INT 21H ;Issue request to DOS
JC Error ;Error code in AX
Fname DB 64 Dup (0) ;ASCIIZ Name
; example: "c:\dir\File.ext",0
Attribute DW ? ;File Attribute
; example: 0001H to set Read-Only
COMMENTS
On entry, AL contains a function code, and DS:DX contains the address of an
ASCIIZ string with the drive, path, and filename.
If AL contains 01H, the file's attribute is set to the attribute in CX. See
"The Disk Directory" on page 2-3 for the attribute byte description. If AL
is 00H the file's current attribute is returned in CX.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
NOTE: Only the Archive (20H), Read-Only (01H), System (04H) and Hidden (02H)
bits can be changed. All other bits of CX must be 0, otherwise, an
error may be indicated.
Network Access Rights: To change the archive bit (AL=20H), no access rights
are required. To change any other bit, Create access rights are required.
44H --
I/O CONTROL FOR DEVICES
PURPOSE
Sets or gets device information associated with open device handles, or sends
control strings to the device handle or receives control strings from the
device handle.
See Appendix C for full details on this function call.
45H --
DUPLICATE A FILE HANDLE (DUP)
PURPOSE
Returns a new file handle for an open file that refers to the same file at
the same position.
EXAMPLE
MOV AH,45H ; Function Call --
; Duplicate a Handle
MOV BX,Handle ; Select File
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV NewHandle,AX ; Save New Handle
Handle DW ? ; File Handle (from Open / Create)
NewHandle DW ? ; File Handle that duplicates Handle
COMMENTS
On entry, BX contains the file handle. On return, AX contains the returned
file handle.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
NOTE: If you move the read/write pointer of either handle by a read, write,
or LSEEK function call, the pointer for the other handle is also
changed.
46H --
FORCE A DUPLICATE OF A HANDLE (FORCDUP)
PURPOSE
Forces the handle in CX to refer to the same file at the same position as the
handle in BX.
EXAMPLE
MOV AH,46H ; Function Call --
; Force Duplicate a Handle
MOV BX,Handle ; Select file
MOV CX,NewHandle ; Select new definition of File
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
Handle DW ? ; File Handle (from Open/Create)
NewHandle DW ? ; File Handle that duplicates Handle
COMMENTS
On entry, BX contains the file handle. CX contains a second file handle. On
return, the CX file handle refers to the same file at the same position as
the BX file handle. If the CX file handle was an open file, it is closed
first. If you move the read/write pointer of either handle, the pointer for
the other handle is also changed.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
47H --
GET CURRENT DIRECTORY
PURPOSE
Places the full path name (starting from the root directory) of the current
directory for the specified drive in the area pointed to by DS:SI.
EXAMPLE
MOV AX,SEG DName ; Directory Name Buffer
MOV DS,AX
MOV SI,OFFSET DName ; OS:SI points to buffer
MOV DL,Drive ; Select Drive
MOV AH,47H ; Function-Get Current Dir
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
Drive DB ? ; Drive (0=current, 1=A:, 2=b:, ...)
DName DB 64 DUP(?) ; ASCIIZ Directory Name Returned
; example: "dir1\dir2",0
COMMENTS
The drive letter is not part of the returned string. The string does not
begin with a backslash and is terminated by a byte containing 00H.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
48H --
ALLOCATE MEMORY
Allocates the requested number of paragraphs of memory.
EXAMPLE
MOV AH,48H ; Function Call --
; Allocate Memory
MOV BX,Paragraphs ; Paragraphs Desired
INT 21H ; Issue request to DOS
JNC Done
MOV AH,48H ; Function Call --
; Allocate memory
; BX set to largest available memory
INT 21H ; Issue request to DOS
Done:
MOV BlockSeg,AX ; Save BlockSeg of memory
MOV Paragraphs,BX
Paragraphs DW ? ; Size requested in paragraphs
; (Bytes allocated is 16 * Paragraphs)
BlockSeg DW ? ; BlockSeg address of allocated memory
COMMENTS
On entry, BX contains the number of paragraphs requested. On return, AX:0
points to the allocated memory block. If the allocation fails, BX returns
the size of the largest block of memory available in paragraphs.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
49H --
FREE ALLOCATED MEMORY
PURPOSE
Frees the specified allocated memory.
EXAMPLE
MOV AH,49H ; Function Call -- Free Memory
MOV ES,BlockSeg ; Set address to free
INT 21H ; Issue request to DOS
JC Error
BlockSeg DW ? ; BlockSeg address of allocated memory
COMMENTS
On entry, ES contains the segment of the block to be returned to the system
pool. On return, the block of memory is returned to the system pool.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
4AH --
MODIFY ALLOCATED MEMORY BLOCKS (SETBLOCK)
PURPOSE
Modifies allocated memory blocks to contain the new specified block size.
EXAMPLE
MOV AH,4AH ; Function Call --
; Modify Allocated Memory; allocate memory
MOV ES,BlockSeg ; Set address to free
MOV BX,BlockSize ; New size (may be larger or smaller)
INT 21H ; Issue request to DOS
JNC Done
MOV AH,4AH ; Function Call --
; Allocate memory
; BX set to largest available Size
INT 21H ; Issue request to DOS
Done:
MOV Size,BX
BlockSeg DW ? ; Segment address of allocated memory
BlockSize DW ? ; Size requested in paragraphs
; (Bytes allocated is 16 * Size)
COMMENTS
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
NOTE: This call is often used to set the size of a program before using
function call 31H (Terminate Process and Remain Resident). Use the
program segment prefix. This value can be obtained using function
call 62H (Get Program Segment Prefix Address). Another use is to
release memory to prepare for using function call 4BH (Load or Execute
a Program).
4BH --
LOAD OR EXECUTE A PROGRAM (EXEC)
PURPOSE
Allows a program to load another program into memory and may choose to begin
execution of it.
EXAMPLE
; To Execute a Program
MOV AH,4BH ; Function Call -- Execute a Program
MOV AL,0 ; Indicate execute program
MOV CX,SEG Parms ; Program parameters
MOV ES,CX
MOV BX,OFFSET Parms : ES:BX points to parameter block
MOV CX,SEG PName ; Program name
MOV DS,CX
MOV DX,OFFSET PName ; DS:DX points to program name
MOV WORD PTR StackSave+0,SP ; Save stack pointer
MOV WORD PTR StackSave+2,SS
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
; Note: All Registers (except CS:IP) Destroyed
; Program Runs here
CLI ; Protect from stack usage
MOV SS,WORD PTR StackSave+2 ; Restore stack pointer
MOV SP,WORD PTR StackSave+0
STI ; Enable interrupts
MOV AH,4DH ; Function Call -- Get Return Code
INT 21H ; Issue request to DOS
MOV RetCode,AX ; Save return code
; To Load an Overlay
MOV AH,4BH ; Function Call -- Execute a Program
MOV AL,3 ; Indicate load overlay
MOV CX,SEG OParms ; Overlay parameters
MOV ES,CX
MOV BX,OFFSET OParms ; ES:BX points to parameter block
MOV CX,SEG PName ; Overlay name
MOV DS,CX
MOV DX,OFFSET PName ; DS:DX points to overlay filename
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
PName DB 64 Dup (0) ; ASCIIZ Name
; example: "c:\dir\File.ext",0
Parms LABEL WORD ; Program parameters
Env@ DW ? ; Environment segment address
; Value of 0000H indicates copy EXEC'ers
; Environment
Cmd@ DD ? ; Command line address
FCB1@ DD ? ; FCB Image to set to New PSP+5CH
FCB2@ DD ? ; FCB Image to set to New PSP+6CH
StackSave DD ? ; Stack pointer save area
RetCode DW ? ; Program return code
; (see function code 4DH for more informatio
OParms LABEL WORD ; Overlay parameters
Load@ DW ? ; Overlay load segment address
RelocFactor DW ? ; Relocation factor to apply (for .EXE files
COMMENTS
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location. Refer to "Responding to Errors" on page B-5 and "Extended Error
Codes" on page B-5 for more information on the codes returned from function
call 59H.
The following function values are allowed in AL:
+---------------------------------------------------------------------------+
| FUNCTION |
| VALUE DESCRIPTION |
+---------------------------------------------------------------------------+
| 00H Load and execute the program. A program segment prefix is |
| established for the program; terminate and Ctrl-Break addresses |
| are set to the instruction after the EXEC system call. |
| |
| NOTE: When control is returned, all registers are changed, |
| including the stack. You must restore SS, SP, and any |
| other required registers before proceeding. |
+---------------------------------------------------------------------------+
| 03H Load, do not create the program segment prefix, and do not |
| begin execution. This is useful in loading program overlays. |
+---------------------------------------------------------------------------+
All open files of a process are duplicated in the newly created process after
an EXEC, unless the file was opened with the inheritance bit set to 1. This
means that the parent process has control over the meanings of standard
input, output, auxiliary, and printer devices. The parent could, for
example, write a series of records to a file, open the file as standard
input, open a listing file as standard output, and then execute a sort
program that takes its input from standard input and writes to standard
output.
Also inherited (or copied from the parent) is an "environment." This is a
block of text strings (less than 32KB total) that conveys various
configuration parameters. The following is the format of the environment
(always on a paragraph boundary):
+---------------------------------------------------------------------------+
| Byte ASCIIZ string 1 |
+---------------------------------------------------------------------------+
| Byte ASCIIZ string 2 |
+---------------------------------------------------------------------------+
| ... |
+---------------------------------------------------------------------------+
| Byte ASCIIZ string n |
+---------------------------------------------------------------------------+
| Byte of 0 |
+---------------------------------------------------------------------------+
Typically the environment strings have the form:
parameter=value
Following the byte of 0 in the environment is a WORD that indicates the
number of other strings following. Following this is a copy of the DS:DX
filename passed to the child process. For example, the string VERIFY=ON
could be passed. A 0 value of the environment address causes the newly
created process to inherit the original environment unchanged. The segment
address of the environment is placed at offset 2CH of the program segment
prefix for the program being invoked.
Errors codes are returned in AX. Refer to "Responding to Errors" on page B-5
and "Extended Error Codes" on page B-5 for more information on the codes
returned.
NOTE: When your program received control, all available memory was allocated
to it. You must free some memory (see call 4AH) before EXEC can load
the program you are invoking. Normally, you would shrink down to the
minimum amount of memory you need, and free the rest.
4CH --
TERMINATE A PROCESS (EXIT)
PURPOSE
Terminates the current process and transfers control to the invoking process.
EXAMPLE
MOV AH,4CH ; Function Call -- Terminate a Process
MOV AL,ErrorCode ; Set ERRORLEVEL
INT 21H ; Issue request to DOS
INT 20H ; Be safe if running on PC/DOS 1.1
ErrorCode DB ? ; Error Code (sets ERRORLEVEL if EXEC'ed
; by COMMAND.COM)
COMMENTS
In addition, a return code can be sent. The return code can be interrogated
by the batch subcommands IF and ERRORLEVEL and by the wait function call 4DH.
All files opened by this process are closed.
4DH --
GET RETURN CODE OF A SUBPROCESS (WAIT)
PURPOSE
Gets the return code specified by another process either through function
call 4CH or function call 31H. It returns the Exit code only once.
EXAMPLE
MOV AH,4DH ; Function Call -- Get Return Code
INT 21H ; Issue request to DOS
MOV RetCode,AX ; Save return code
RetCode LABEL WORD ; Program return code
ExitCode DB ? ; ERRORLEVEL value
ExitType DB ? ; Method used to exit:
; 00H -- for normal termination
; 01H -- for termination by Ctrl-Break
; 02H -- for termination as a result
; of a critical device error
; 03H -- for termination by call 31H
COMMENTS
The low byte of the exit code contains the information sent by the exiting
routine.
4EH --
FIND FIRST MATCHING FILE (FIND FIRST)
PURPOSE
Finds the first filename that matches the specified file specification.
EXAMPLE
MOV AH,1AH ; Function Call -- Set DTA Address
MOV CX,SEG DTA ; Address buffer for found file
MOV DS,CX
MOV DX,OFFSET DTA
INT 21H ; Issue request to DOS
MOV AH,4EH ; Function Call -- ASCIIZ Find First
MOV CX,SEG FName ; Directory or filename
MOV DS,CX
MOV DX,OFFSET FName ; DS:DX points to ASCII filename
MOV CX,Attribute ; Set Match Attribute
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
DTA LABEL BYTE ; Find return information
DB 21 DUP(0) ; Reserved for DOS 4.00 to continu
FileAttr DB ? ; Matched files attribute low byte
FileTime DW ? ; File time
FileDate DW ? ; File date
FileSize DD ? ; File size
FileNameExt DB "????????.???",0 ; Filename and extension
FName DB 64 DUP (0) ; ASCIIZ Name
; example: "c:\dir\*.*",0
Attribute DW ? ; Select files attribute
; Combination of following:
; 0002H=Hidden
; 0004H=System
; 0008H=Volume label
; 0010H=Directory
NOTES:
If an extended FCB is used, the following search pattern is used:
1. If the attribute is 0, only normal file entries are found. Entries for
volume label, sub-directories, hidden and system files are not returned.
2. If the attribute field is set for hidden or system files, or directory
entries, it is to be considered as an inclusive search. All normal file
entries plus all entries matching the specified attributes are returned.
To look at all directory entries except the volume label, the attribute
byte may be set to hidden + system + directory (all 3 bits on).
3. If the attribute field is set for the volume label, it is considered an
exclusive search, and only the volume label entry is returned.
COMMENTS
The filename in DS:DX can contain global filename characters. The ASCIIZ
string cannot contain a network path. See function call 11H (Search for
First Entry) for a description of how the attribute bits are used for
searches.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location. Refer to "Responding to Errors" on page B-5 and "Extended Error
Codes" on page B-5 for more information on the codes returned from function
call 59H.
NOTE: The name and extension of file found is returned as an ASCIIZ string.
All blanks are removed from the name and extension, and, if an
extension is present, it is preceded by a period.
4FH --
FIND NEXT MATCHING FILE (FIND NEXT)
PURPOSE
Finds the next directory entry matching the name that was specified on the
previous Find First or Find Next function call.
EXAMPLE
MOV AH,1AH ; Function Call -- Set DTA Address
MOV CX,SEG DTA ; Address buffer for found file
MOV DS,CX
MOV DX,OFFSET DTA
INT 21H ; Issue request to DOS
MOV AH,4FH ; Function Call -- Find next
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
DTA LABEL BYTE " ; Find Return Information
DB 21 DUP(0) " ; Reserved for DOS to Continue Find
" ; Set by Find First or Previous Fin
FileAttr DB ? " ; Matched Files Attribute Low Byte
FileTime DW ? " ; File Time
FileDate DW ? " ; File Date
FileSize DD ? " ; File Size
FileNameExt DB "????????.???",0 ; File Name and Extension
COMMENTS
If a matching file is found, the DTA is set as described in call 4EH (Find
First Matching File (FIND FIRST)). If no more matching files are found, an
error code is returned.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location.
54H --
GET VERIFY SETTING
PURPOSE
Returns the value of the verify flag.
EXAMPLE
MOV AH,54H ; Function Call -- Get VERIFY Setting
INT 21H ; Issue request to DOS
MOV VERIFY,AL ; Save VERIFY State
VERIFY DB ? ; VERIFY State:
; 0 = OFF
; 1 = ON
COMMENTS
On return, AL returns 00H if verify is OFF, 01H if verify is ON. Note that
the verify switch can be set through call 2EH (Set/Reset Verify Switch).
56H --
RENAME A FILE
PURPOSE
Renames the specified file.
EXAMPLE
MOV AH,56H ; Function Call -- ASCIIZ Rename File
MOV CX,SEG FName ; File Name
MOV DS,CX
MOV DX,OFFSET FName ; DS:DX points to original name
MOV CX,SEG NewName ; New File Name
MOV ES,CX
MOV DI,OFFSET NewName ; ES:DI points to rename
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
FName DB 64 DUP (0) ; ASCIIZ Name
; example: "c:\dir\abc.lst",0
NewName DB 64 DUP (0) ; ASCIIZ Name
; example: "\dir\xyz.lst",0
COMMENTS
If a drive is used in the NewName string, it must be the same as the drive
specified or implied in the Name string. The directory paths need not be the
same, allowing a file to be moved to another directory and renamed in the
process. Directory names can be changed but not moved. Global filename
characters are not allowed in the filename.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location. Refer to "Responding to Errors" on page B-5 and "Extended Error
Codes" on page B-5 for more information on the codes returned from function
call 59H.
Network Access Rights: Requires Create access rights.
57H --
GET/SET FILE'S DATE AND TIME
PURPOSE
Gets or sets a file's date and time.
EXAMPLE
; To Get a File's Date and Time
MOV AH,57H ; Function Call -- Get/Set Date and Time
MOV AL,0 ; Indicate get
MOV BX,Handle ; Select file
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV FileTime,CX ; Save Time
MOV FileDate,DX ; Save Date
; To Set a File's Date and Time
MOV AH,57H ; Function Call -- Get/Set Date and Time
MOV AL,1 ; Indicate Set
MOV BX,Handle ; Select file+
MOV CX,FileTime ; Set Time
MOV DX,FileDate ; Set Date
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
Handle DW ? ; File Handle (from Open / Create)
FileTime DW ? ; File Time
FileDate DW ? ; File Date
COMMENTS
The date and time formats are the same as those for the directory entry
described in Chapter 5 of this book.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location. Refer to "Responding to Errors" on page B-5 and "Extended Error
Codes" on page B-5 for more information on the codes returned from function
call 59H.
59H --
GET EXTENDED ERROR
PURPOSE
Returns additional error information, such as the error class, location, and
recommended action.
EXAMPLE
PUSH DX ; Save Registers
PUSH SI
PUSH DI
PUSH ES
PUSH DS
MOV AH,59H ; Function Call -- Get Extended Error
MOV BX,0 ; Version 0 information
INT 21H ; Issue request to DOS
POP DS ; Restore registers
POP ES
POP DI
POP SI
POP DX
MOV ExtError,AX ; Save error code
MOV ErrorClass,BH ; Save error class
MOV ErrorAction,BL ; Save error action
MOV ErrorLocation,CH; Save error location
ExtError DW ? ; DOS extended error
ErrorClass DB ? ; Class of error
ErrorAction DB ? ; Suggested action
ErrorLocation DB ? ; System area effected
COMMENTS
This function call returns the error class, location, and recommended action,
in addition to the return code. Use this function call from:
Interrupt 24H error handlers
Interrupt 21H function calls that return an error in the carry bit
FCB function calls that return FFH.
On return, the registers contents of DX, SI, DI, ES, CL, and DS are
destroyed.
ERROR RETURN IN CARRY BIT
For function calls that indicate an error by setting the carry flag, the
correct method for performing function call 59H is:
Load registers.
Issue interrupt 21H.
Continue operation, if carry not set.
Disregard the error code and issue function call 59H to obtain additional
information.
Use the value in BL to determine the suggested action to take.
ERROR STATUS IN AL
For function calls that indicate an error by setting AL to FFH, the correct
method for performing function call 59H is:
Load registers.
Issue interrupt 21H.
Continue operation, if error is not reported in AL.
Disregard the error code and issue function call 59H to obtain additional
information.
Use the value in BL to determine the suggested action to take.
5AH --
CREATE UNIQUE FILE
PURPOSE
Generates a unique filename, and creates that file in the specified
directory.
EXAMPLE
MOV AH,5AH ; Function Call -- Create a
; Unique File
MOV CX,SEG DirName ; Directory name
MOV DS,CX
MOV DX,OFFSET DirName
MOV CX,Attribute ; File attribute
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV Handle,AX ; Save file handle for following
; Operations
DirName DB "?? .. ??\",0 ; ASCIIZ name
DB "????????.???"
; example in : "c:\dir\",0
; example out: "c:\dir\file",0
Handle DW ? ; File handle
Attribute DW ? ; Select file's attribute
COMMENTS
On entry, AH contains 5AH. If no error has occurred, the file is opened in
compatibility mode with Read/Write access. The read/write pointer is set at
the first byte of the file and AX contains the file handle and the filename
is appended to the path specified in DS:DX.
This function call generates a unique name and attempts to create a new file
in the specified directory. If the file already exists in the directory,
then another unique name is generated and the process is repeated. Programs
that need temporary files should use this function call to generate unique
filenames.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location. Refer to "Responding to Errors" on page B-5 and "Extended Error
Codes" on page B-5 for more information on the codes returned from function
call 59H.
NOTE: The file created using this function call is not automatically deleted
at program termination.
Network Access Rights: Requires Create access rights.
5BH --
CREATE NEW FILE
PURPOSE
Creates a new file.
EXAMPLE
MOV AH,5BH ; Function Call -- Create a New File
MOV CX,SEG FName ; File Name
MOV DS,CX
MOV DX,OFFSET FName
MOV CX,Attribute
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV Handle,AX ; Save File Handle for following operations
FName DB 64 DUP (0) ; ASCIIZ Name
; example: "c:\dir\file",0
Handle DW ? ; File Handle
Attribute DW ? ; Select File's Attribute
COMMENTS
This function call is the same as function call 3CH (Create), except it will
fail if the filename already exists. The file is created in compatibility
mode for reading and writing and the read/write pointer is set at the first
byte of the file.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location. Refer to "Responding to Errors" on page B-5 and "Extended Error
Codes" on page B-5 for more information on the codes returned from function
call 59H.
Network Access Rights: Requires Create access rights.
5CH --
LOCK/UNLOCK FILE ACCESS
PURPOSE
Locks or unlocks a single range of bytes in an opened file. This function
call provides database services that are useful in maintaining database
integrity in a network environment.
EXAMPLE
; To Lock a Single Range
MOV AH,5CH ; Function Call --
; Access Lock/Unlock File
MOV AL,0 ; Indicate lock
MOV BX,Handle ; Select file
MOV DX,WORD PTR Position+0 ; Set position
MOV CX,WORD PTR Position+2
MOV DI,WORD PTR Llength+0 ; Set length
MOV SI,WORD PTR Llength+2
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
; To Unlock a Single Range
MOV AH,5CH ; Function Call --
; Lock/Unlock File Access
MOV AL,1 ; Indicate unlock
MOV BX,Handle ; Select file
MOV DX,WORD PTR Position+0 ; Set position
MOV CX,WORD PTR Position+2
MOV DI,WORD PTR Llength+0 ; Set length
MOV SI,WORD PTR Llength+2
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
Handle DW ? ; File Handle
Position DD ? ; Start of Range
Llength DD ? ; Length of Range
COMMENTS
The Lock/Unlock function calls should only be used when a file is opened
using the DenyRead or DenyNone sharing modes. These modes do no local
buffering of data when accessing files on a network disk.
AL = 00H LOCK
Provides a simple mechanism for excluding other processes' read/write access
to regions of the file. If another process attempts to read or write in such
a region, its system call is retried the number of times specified with the
system retry count set by IOCTL. If, after those retries, no success occurs,
a general failure error is generated, signaling the condition. The number of
retries, as well as the length of time between retries, can be changed using
function call 440BH (IOCTL Change Sharing Retry Count).
The recommended action is to issue function call 59H (Get Extended Error) to
get the error code, in addition to the error class, location, and recommended
action. The locked regions can be anywhere in the logical file. Locking
beyond end-of-file is not an error. It is expected that the time in which
regions are locked will be short. Duplicating the handle duplicates access
to the locked regions. Access to the locked regions is not duplicated across
the EXEC system call. Exiting with a file open and having issued locks on
that file has undefined results.
Programs that may be cancelled using INT 23H (File Size) or INT 24H (Set
Relative Record Field) should trap these and release the locks before
exiting. The proper method for using locks is not to rely on being denied
read or write access, but to attempt to lock the region desired and examining
the error code.
AL = 01H UNLOCK
Unlock releases the lock issued in the lock system call. The region
specified must be exactly the same as the region specified in the previous
lock. Closing a file with locks still in force has undefined results.
Exiting with a file open and having issued locks on that file has undefined
results.
Programs that may be aborted using INT 23H (File Size) or INT 24H (Set
Relative Record Field) should trap these and release the lock before exiting.
The proper method for using locks is not to rely on being denied read or
write access, but attempting to lock the region desired and examining the
error code.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location. Refer to "Responding to Errors" on page B-5 and "Extended Error
Codes" on page B-5 for more information on the codes returned from function
call 59H.
5E00H --
GET MACHINE NAME
PURPOSE
Returns the character identifier of the local computer.
EXAMPLE
MOV AX,SEG CNAME ; Name buffer
MOV DS,AX
MOV DX OFFSET CNAME
MOV AX,5E00H ; Function Call --
; Get Machine Name
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV NameFlag,CH ; Save name number indicator
MOV NameID,CL ; Save NETBIOS name number
CName DB "???????????????",0 ; ASCIIZ computer name
NameFlag DB ? ; 0 = Name is not set
; 1 = Name is set
NameID DB ? ; NETBIOS name number
COMMENTS
Get Machine Name returns the text of the current computer name to the caller.
The computer name is a 15-character byte string padded with spaces and
followed by a 00H byte. If the computer name was never set, register CH is
returned with 00H and the value in the CL register is invalid. The IBM PC
Local Area Network program must be loaded for the function call to execute
properly.
5E02H --
SET PRINTER SETUP
PURPOSE
Specifies an initial string for printer files.
EXAMPLE
MOV AX,5E02H ; Function Call --
; Set Printer Setup
MOV BX,Index ; Redirection List Index
MOV CX,size ; String size
MOV SI,SEG String ; String Buffer
MOV DS,SI
MOV SI,OFFSET String
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
Index DW ? ; Redirection List Index
Size DW N ; String size (Maximum 64)
String DB N DUP(?) ; Printer Setup String
COMMENTS
The string specified is put in front of all files destined for a particular
network printer. Set Printer Setup allows multiple users of a single printer
to specify their own mode of operation for the printer. BX is set to the
same index that is used in function call 5F02H (Get Redirection List Entry).
An error code is returned if print redirection is paused or if the IBM PC
Local Area Network program is not loaded.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location. Refer to "Responding to Errors" on page B-5 and "Extended Error
Codes" on page B-5 for more information on the codes returned from function
call 59H.
IMPORTANT: The redirection index value may change if function call 5F03H
(Redirect Device) or function call 5F04H (Cancel Redirection) is issued
between the time the redirection list is scanned and the function call 5E02H
(Set Printer Setup) is issued. Therefore, we recommend that you issue Set
Printer Setup immediately after you issue "Get Redirection List ."
5E03H --
GET PRINTER SETUP
PURPOSE
Returns the printer setup string for printer files.
EXAMPLE
MOV AX,5E03H ; Function Call --
; Get Printer Setup
MOV BX,Index ; Redirection List Index
MOV CX,SEG String ; String Buffer
MOV ES,CX
MOV DI,OFFSET String
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV Ssize, CX ; Save String size
Index DW ? ; Redirection List Index
Ssize DW ? ; String size
String DB 64 DUP(?) ; Printer Setup String
COMMENTS
This function call returns the printer setup string which was specified using
the function call 5E02H (Set Printer Setup). The setup string is attached to
all files destined for a particular printer. The value in BX is set to the
same index issued in function call 5F02H (Get Redirection List). Error code
1 (invalid function number) is returned if the IBM PC Local Area Network is
not loaded.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location. Refer to "Responding to Errors" on page B-5 and "Extended Error
Codes" on page B-5 for more information on the codes returned from function
call 59H.
IMPORTANT: The redirection index value may change if function call 5F03H
(Redirect Device) or function call 5F04H (Cancel Redirection) is issued
between the time the redirection list is scanned and the function call 5E03H
(Get Printer Setup) is issued. Therefore, we recommend that you issue "Get
Printer Setup" immediately after you issue "Get Redirection List."
5F02H --
GET REDIRECTION LIST ENTRY
PURPOSE
Returns nonlocal network assignments.
EXAMPLE
MOV BX,0 ; Start at beginning of list
Get_Loop: ; Get next entry
MOV Index,BX ; Redirection list index
MOV AX,5F02H ; Function Call --
; Get redirection list entry
MOV SI,SEG device ; "PRN" is possible
MOV DS,SI
MOV SI,OFFSET device ; DS:SI points to local name
MOV DI,SEG info
MOV ES,DI
MOV DI,OFFSET inf ; ES:DI points to buffer address of netwo
PUSH BX
PUSH DX ; Save registers
PUSH BP
INT 21H ; Issue request to DOS
POP BP ; Restore registers
POP DX
JC CheckEnd ; Error code in AX
MOV Status,BH ; Save status
MOV Type,BL ; Save type
MOV UserParm,CX ; Save user parmameter
POP BX
INC BX ; Set to next entry
JMP Get_Loop
CheckEnd:
POP BX ; Balance state
CMP AX,18 ; End of list?
JNE Error ; No!
Index DW ? ; Redirection list index (0 based)
Device DB 128 DUP(?) ; ASCIIZ device name
; example: "LPT1",0
; "A:",0
Status DB ? ; Device status
; Bit 0=0 : Device is OK
; Bit 0=1 : Device in Error
; Bit 7-1 reserved
UserParm DW ? ; User parameter
Type DB ? ; Device type
; 3 = NET USE device
; 4 = NET USE drive
Info DB 128 DUP(?) ; NET USE network path
; example: "\\MYNODE\CDRIVE",0
COMMENTS
The Get Redirection List Entry function call returns the list of network
redirections that were created through function call 5F03H (Redirect Device).
Each call returns one redirection, so BX should be increased by one each time
to step through the list. The contents of the list may change between calls.
The end-of-list is detected by error code 18 (no more files). Error code 1
(invalid function number) is returned if the IBM PC Local Area Network
program is not loaded.
If either disk or print redirection is paused, the function is not effected.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location. Refer to "Responding to Errors" on page B-5 and "Extended Error
Codes" on page B-5 for more information on the codes returned from function
call 59H.
5F03H --
REDIRECT DEVICE
PURPOSE
Causes a Redirector/Server connection to be made.
EXAMPLE
MOV AX,5F03H ; Function Call --
; Redirect Device
MOV SI,SEG Device ; Device Buffer
MOV DS,SI
MOV SI,OFFSET Device
MOV DI,SEG Net Path info ; Information Buffer
MOV ES,DI
MOV DI,OFFSET Net Path
MOV BL,Type ; Set Type
MOV CX,UserParm ; Set User Parameter
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
Device DB "....",0 ; ASCIIZ Device Name
; example: "LPT1",0
; "A:",0
UserParm DW ? ; User Parameter
Type DB ? ; Device Type
; 3 = NET USE Device
; 4 = NET USE Drive
Net Path DB 128 DUP(0)
COMMENTS
This call defines the current directories for the network and defines
redirection of network printers.
If BL = 03, the source specifies a printer, the destination specifies a
network path, and the CX register has a word that DOS 4.00 maintains for
the programmer. For compatibility with the IBM PC Local Area Network
program, CX should be set to 0. Values other than 0 are reserved for the
IBM PC Local Area Network program. This word may be retrieved through
function call 5F02H (Get Redirection List). All output destined for the
specified printer is buffered and sent to the remote printer spool for
that device. The printers are redirected at the INT 17H level.
The source string must be PRN , LPT1, LPT2, or LPT3 each ended with a
00H. The destination string must point to a network name string of the
following form:
[\\computername\¤shortname|printdevice‡]
The destination string must be ended with a 00H.
The ASCIIZ password (0 to 8 characters) for access to the remote device
should immediately follow the network string. The password must end with
a 00H. A null (0 length) password is considered to be no password.
If BL = 4, the source specifies a drive letter and colon ending with 00H,
the destination specifies a network path ending with 00H, and the CX
register has a word that DOS maintains for the programmer. For
compatibility with the IBM PC Local Area Network program, CX should be
set to 00H. Values other than 00H are reserved for the IBM PC Local Area
Network program. The value may be retrieved through function call 5F02H
(Get Redirection List). If the source was a drive letter, the
association is made between the drive letter and the network path. All
subsequent references to the drive letter are translated to references to
the network path. If the source is an empty string, the system attempts
to grant access to the destination with the specified password without
redirecting any device.
The ASCIIZ password for access to the remote path should immediately
follow the network string. A null (0 length) password ended with 00H is
considered to be no password.
Error codes are returned in AX. Issue function call 59H for additional
information about the error class, suggested action, and location. Refer
to "Responding to Errors" on page B-5 and "Extended Error Codes" on
page B-5 for more information on the codes returned from function call
59H (Get Extended Error) .
NOTES:
1. Devices redirected through this function call are not displayed by the
NET USE command.
2. An error is returned if you try to redirect a drive while disk
redirection is paused, or if you try to redirect a printer while print
redirection is paused.
5F04H --
CANCEL REDIRECTION
PURPOSE
Cancels a previous redirection.
EXAMPLE
MOV AX,5F04H ; Function Call --
; Cancel redirection
MOV SI,SEG Device ; Device buffer
MOV DS,SI
MOV SI,OFFSET Device
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
Device DB "....",0 ; ASCIIZ Device Name
; example: "LPT1",0
; "A:",0
; "\\Computer\Path",0
COMMENTS
The redirection created by the Redirect Device function call (5F03H) is
removed through the Cancel Redirection call. If the buffer points to a drive
letter and the drive is associated with a network name, the association is
ended and the drive is restored to its physical meaning. If the buffer
points to PRN, LPT1, LPT2, or LPT3, and the device has an association with a
network device, the association is terminated and the device is restored to
its physical meaning. If the buffer points to a network path ending with 00H
and a password ending with 00H, the association between the local machine and
the network directory is terminated.
An error is returned if you try to cancel a redirected file device while disk
redirection is paused, or if you try to cancel a redirected printer while
print redirection is paused. Error code 1 (invalid function number) is
returned if the IBM PC Local Area Network program is not loaded.
Error codes are returned in AX. Issue function call 59H (Get Extended Error)
for additional information about the error class, suggested action, and
location. Refer to "Responding to Errors" on page B-5 and "Extended Error
Codes" on page B-5 for more information on the codes returned from function
call 59H.
62H --
GET PROGRAM SEGMENT PREFIX ADDRESS
PURPOSE
Returns the program prefix address.
EXAMPLE
MOV AH,62H ; Function Call --
; Get Program Segment Prefix Address
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV PSPSeg,BX ; Save PSP address
PSPSeg DW ? ; Segment address of my PSP
COMMENTS
The internal PSP address for the currently executing process is returned in
BX.
65H --
GET EXTENDED COUNTRY INFORMATION
PURPOSE
Returns extended country information.
EXAMPLE
; To get information
MOV AH,65H ; Function Call --
; Get extended country information
MOV AL,InfoID ; Data/function requested
; (1, 2, 4, 6 or 7).
MOV BX,CodePage ; Set desired code page
; (-1=current, Set by function call 6602H).
MOV CX,SizeBuffer ; Maximum data to return
; (must be >= 5)
MOV DX,CountryID ; Set desired Country ID
; (-1=current, set by function call 38H).
MOV DI,SEG Buffer ; Information return buffer
MOV DS,DI
MOV DI,OFFSET Buffer
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
Buffer LABEL BYTE
; Format depends on AL value
; AL=1 : Extended Country Information
SizeBuffer DW ? ; Size of data block to return
InfoID DB ? ; Type of info to get
CIinfoSize DW ? ; amount of data that follows
; (limited by CX input)
CountryID DW ? ; Selected CountryID
CodePage DW ? ; Selected Code Page
; See function call 38H for the format of the remainder of this buffer
; AL=2 : Upper Case Table
DB 2 ; Indicates Upper Case Table
UpperCase@ DD ? ; Address of Upper Case Table
; AL=4 : File Upper Case Table
DB 4 ; Indicates File Upper Case Table
UpperCase@ DD ? ; Address of File Upper Case Table
; AL=6 : Collating Table
DB 6 ; Indicates Collate Table
Collate@ DD ? ; Address of Collate Table
; AL=7 : DBCS Vector Table
DB 7 ; Indicates DBCS Vector Table
DBCS@ DD ? ; Address of DBCS Vector Table
COMMENTS
On entry, DX contains the ID of the country for which the extended
information is needed. AL contains the ID value for the country.
If the country code and code page do not match, or if either one or both
are invalid, an error code of 2 (file not found) is returned in AX.
The size requested in CX must be 5 or greater. If it is less than 5, an
error code of 1 is returned in AX.
If the amount of information returned is greater than the size requested
in CX, it is ended and no error is returned in AX.
NOTE: For further information on the country information, see function call
38H (Get or Set Country Dependent Information).
The NLSFUNC DOS extension must be installed to get information for
countries other than the Current Country.
The uppercase table and the filename uppercase tables are 130 bytes long,
consisting of a length field (2 bytes), followed by 128 uppercase values for
the upper 128 ASCII characters. They have the following layout:
Tsize DW 128 ; Table Size
Table DB 128 DUP(?) ; Upper case versions of 80H to FFH
The following formula can be used to determine the address of an uppercase
equivalent for a lowercase character (ASCII in) in the uppercase table or the
filename uppercase table.
EXAMPLE
ASCII in -(256-table len)+table start= address of ASCII out
WHERE
ASCII in = character to be generated
table len = length of list of uppercase
values (2 bytes)
table start = starting address of uppercase
table (4 bytes)
ASCII out = uppercase value for ASCII in
If the value of ASCII in is equal to or greater than (256-table len), there
is an uppercase equivalent for ASCII in in the table. If it is lower than
(256-table len), no uppercase equivalent exists in the table.
The collate table is 258 bytes long, consisting of a length field (2 bytes)
followed by 256 ASCII values, in the appropriate order. It has the following
layout:
Tsize DW 256 ; Table Size
Table DB 256 DUP(?) ; Sort Weights for 00H to FFH
The DBCS vector is variable in length, consisting of a length field (two
bytes) followed by one or more pairs of bytes. It has the following layout:
Tsize DW Nx2 ;List size
1 DB Start,end ;DBCS vector 1
2 DB Start,end ;DBCS vector 2
:
N DB Start,end ;DBCS vector n
DB 0,0 ;End marker
66H --
GET/SET GLOBAL CODE PAGE
PURPOSE
This function gets or sets the code page for the current country.
MOV AX,6601H ; Function Call --
; Get Global Code Page
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV GlobalCP,BX ; Save Global Code Page
MOV SystemCP,DX ; Save DOS System Code Page
or
MOV AX,6602H ; Function Call --
; Set Global Code Page
MOV BX,GlobalCP ; New Global Code Page
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
GlobalCP DW ? ; Current Code Page of DOS Country Informati
SystemCP DW ? ; Code Page of DOS messages
; Often the default Code Page for the
; current country
COMMENTS
DOS 4.00 moves the new code page data from the COUNTRY.SYS file to a resident
country buffer area. DOS 4.00 uses the new code page to perform a Select to
all attached devices that are set up for code page switching, (that is, have
a code page switching device driver specified in CONFIG.SYS). If any device
fails to be selected, an error code of 65 is returned in AX. The code page
must be recognizable by the current country, and DOS 4.00 must be able to
open and read from the country information file. Otherwise, the carry flag
will be set on return and AX will contain 02 (file not found).
NOTE: NLSFUNC must be installed to use this function call, and all the
devices must be prepared in order for the Select function to be
successful.
67H --
SET HANDLE COUNT
PURPOSE
Permits more than 20 open files per process.
EXAMPLE
EntryPoint:
MOV AH,62H ; Function Call --
; Get PSP Address
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV ES,BX ; Set Segment
MOV AH,4AH ; Function Call --
; Set Memory Block Size
MOV BX,paragraphs ; Set Size
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
MOV AH,67H ; Function Call - Set Handle Count
MOV BX,NewHandles ; Set new handle count
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
NewHandles DW ? ; Number of Handles need
; by this DOS 4.00 proce
ListSize EQU (Endofprogram - EntryPoint) ; Number of bytes
Paragraphs EQU (ListSize / 10H) ; Number of paragraphs
End_of_program LABEL BYTE ; Last used position for
; this program
COMMENTS
The maximum number of file handles allowed for this interrupt is 64KB. If
the the specified number of allowable handles is less than the current number
allowed, the specified number will become current only after all the handles
above the specified number have been closed. If the specified number is less
than 20, the number is assumed to be 20. Data base applications can use this
function to reduce the need to swap handles.
You must release memory for DOS 4.00 to contain the extended handle list.
You can do this by using the SET BLOCK (4AH) function call.
68H --
COMMIT FILE
PURPOSE
Causes all buffered data for a file to be written to the device. This
function can be used instead of a close-open sequence.
EXAMPLE
MOV AH,68H ; Function Call -- Commit File
MOV BX,Handle ; Select file
INT 21H ; Issue request to DOS
JC Error ; Error code in AX
Handle DW ? ; Handle from previous Open or Create
COMMENTS
Commit File provides a faster and more secure method of committing data in
multi-user environments such as the IBM PC Local Area Network.
6CH --
EXTENDED OPEN/CREATE
PURPOSE
Optionally opens and creates a file.
EXAMPLE
MOV AH,6CH ; Extended open
MOV AL,0 ; Reserved
MOV BX,MODE ; Open mode
; Format : 0WF00000ISSS0AAA
; AAA=Access code 0=Read
; 1=Write
; 2=Read/Write
; SSS=Sharing mode 0=Compatibility
; 1=DenyRead/Write
; 2=DenyWrite
; 3=DenyRead
; 4=DenyNone
; I 0=Pass handle to chile, 1=No inherit
; F 0=INT 24H, 1=Return error
; on this open and any I/O to this handle
; W 0=No commit, 1=Auto-Commit on write
MOV CX,ATTR ; Create attribute (ignored if open)
MOV DX,FLAG ; Function control, Format=0000000NNNNEEEE
; NNNN=Does not exist action
; 0=Fail, 1=Create
; EEEE=Exists action
; 0=Fail, 1=open, 2=Replace/Open
MOV SI,SEG file name ; Name to open or create
MOV DS,SI
MOV SI,OFFSET file name
INT 21H
JC ERROR
; AX=Handle
; CX=Action taken code
; 1=File opened
; 2=File created/opened
; 3=File replaced/opened
;----
Mode DW ? ; Open mode bit
; Definitions
Attr DW ? ; File attributes
Flag DW ? ; Function definition
File name 64 DUP (0)
COMMENTS
Function 6CH combines the functions currently available with OPEN, CREATE and
a CREATE NEW.
If F is 1, the critical error handler (Interrupt 24) is disabled for the
handle returned by Extended Open. Any I/O issued to this handle will never
generate the critical error but only the extended error.
If F is 0, no actions are taken.
If W is 1, any disk write using the handle returned by Extended Open will
accompany with a commit call (see Interrupt 21H (AL=68H)).
If W is 0, no actions are taken.