DOS 4.00 Technical Reference and Application Programming: Difference between revisions

From OS2World.Com Wiki
Jump to navigation Jump to search
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<PRE>
The '''DOS 4.00 Technical Reference and Application Programming''' is an additional purchase item written for programmer's who develop applications for IBM Personal Computers and Personal System/2.
DOS 4.00: TECHNICAL REFERENCE AND APPLICATION PROGRAMMING                                                       
:15F0256
                                                                               
:1988
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


</PRE>
It consists of the following materials:
* DOS Version 4.00 Technical Reference
* DOS Version 4.00 Technical Quick Reference
* Conditions of Use Statement
* 3.5" (720KB) DOS Utilities Diskette
* 5.25" (360KB) DOS Utilities Diskette


==Chapter 1==
==Contents==
<PRE>
# Introduction
CHAPTER 1.  INTRODUCTION 7
# Accessing Disks
Organization of this Book 16
# Accessing Files With File Handles
New DOS 4.00 Services 43
# Accessing Files Using File Control Blocks
The Utilities Diskette 57
# Managing Device I/O
Minimum Hardware Configuration 79
# Controlling Processes
 
# Creating OBJECT CODE LIBRARIES
CHAPTER 1.  INTRODUCTION                                                       
# Creating an Executable File
                                                                               
# Converting File Formats
This chapter provides information about this book, including the following:   
# Debugging a Program
                                                                               
:A. DOS 4.00 Interrupts
    Organization of the book for quick information retrieval                   
:B. DOS 4.00 Function Calls
    New and enhanced DOS 4.00 services                                         
:C. I/O Control for Devices (IOCTL)
    Contents of the utilities diskette                                         
:D. Expanded Memory Support
    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 9==
<PRE>
CHAPTER 9.  CONVERTING FILE FORMATS 8
The EXE2BIN.EXE Utility 13
Entering Input to EXE2BIN 34
Two Types of Conversion 61
Device Drivers 66
Standard .COM File 100
 
CHAPTER 9.  CONVERTING FILE FORMATS                                           
                                                                               
This chapter describes how to use EXE2BIN.EXE on your utilities diskette to   
convert an .EXE file to a .COM file format.                                   
                                                                               
THE EXE2BIN.EXE UTILITY                                                       
                                                                               
EXE2BIN is useful if you have a simple .EXE file that doesn't need the DOS     
preparation that an .EXE file usually requires, such as telling the program   
its location in memory and setting up a stack for it to use.  Converting an   
.EXE file to a .COM format makes the file more compact and enables it to load 
faster.                                                                       
                                                                               
To qualify for EXE2BIN conversion, your .EXE file has to meet these criteria: 
                                                                               
    The file format must be a valid .EXE one, as produced by the IBM Linker.   
    Actual code and data in the file (the resident portion of the program)    
must be less than 64KB.                                                       
    Only one segment can be declared; therefore, the file cannot define a     
STACK segment.                                                                 
    If the file is to be loaded by the DOS 4.00 command processor, the IBM     
Macro Assembler ORG statement must set the location pointer of the file       
at 100H.                                                                       
    The IBM Macro Assembler END statement must specify the first location as   
the starting address.                                                         
                                                                               
ENTERING INPUT TO EXE2BIN                                                     
                                                                               
Input to EXE2BIN must be entered at the command line and has the following     
format:                                                                        
                                                                               
Note that the only parameter required by EXE2BIN is the filename of the input 
file. If you specify only a filename, EXE2BIN looks for a file with an .EXE   
extension in the current directory of the default drive.  The output file     
created by a successful conversion has the same filename with a .BIN           
extension.                                                                     
                                                                               
For example, suppose you have a file called MYFILE.EXE in your current         
working directory that meets EXE2BIN's conversion criteria. To have EXE2BIN   
convert the file, you can enter:                                               
                                                                               
EXE2BIN MYFILE                                                                 
                                                                               
EXE2BIN creates a memory image of MYFILE.EXE and copies it to the output       
file.  The new file named MYFILE.BIN is placed in your current working         
directory.                                                                     
                                                                               
Of course, you can specify any of these optional parameters.  If you specify   
a drive and path for your input file and do not specify an output             
specification, the output file is placed on the current drive and directory.   
                                                                               
NOTE:  This is a change from previous versions of DOS.                         
                                                                               
TWO TYPES OF CONVERSION                                                       
                                                                               
Two types of .EXE file conversion are possible, depending on how the entry     
point of your program is defined.                                             
                                                                               
DEVICE DRIVERS                                                                 
                                                                               
The first type of conversion is for a program that will be loaded at the       
absolute memory address specified by a user application or by DOS 4.00 at     
system initialization.  An example of this kind of program is a device         
driver.                                                                       
                                                                               
CS:IP is not specified in the program (the .EXE file header contains 0:0 as   
the program's entry point).  Segment fixups are allowed in this type of       
conversion.  If segment fixups are necessary, (that is, your program contains 
instructions requiring segment relocation), you are prompted for the fixup     
value.  Here are some examples of code that will cause prompting for fixup     
values:                                                                       
                                                                               
    You have used the SEG operator:                                           
                                                                               
symbol1  db  "e:\filename",0                                                   
symbol2  dw  SEG symbol1  ;explicit use of SEG                                 
symbol3  dw  symbol1      ;implicit use of OFFSET                             
                                                                               
    You have used a segment name as an immediate field of instruction:         
                                                                               
myseg    SEGMENT    PUBLIC                                                     
                                                                               
.                                                                             
.                                                                             
.                                                                             
MOV      AX,MYSEG          ; fixup                                             
                                                                               
The fixup value is the absolute segment at which the program is to be loaded. 
                                                                               
The DOS 4.00 command processor is not capable of properly loading this type   
of program.                                                                   
                                                                               
STANDARD .COM FILE                                                             
                                                                               
To produce standard .EXE files that are suitable for EXE2BIN conversion, you   
must use the Macro Assembler ORG statement to set the location pointer of the 
file at 100H and specify the first location as the start address in the END   
statement.                                                                     
                                                                               
ORG  100H                                                                     
START                                                                         
.                                                                             
.                                                                             
.                                                                             
END START                                                                     
                                                                               
When EXE2BIN sees that CS:IP is specified as 0000:100H, it assumes that the   
file is to be run as a standard .COM file, with the location pointer set at   
100H by the ORG statement.  No segment fixups are possible because standard   
.COM files must be segment relocatable.  Once the conversion is complete, you 
may rename the resultant file to a .COM extension.  Then the command           
processor is capable of loading and executing the program in the same manner   
as the .COM programs supplied on your DOS 4.00 diskette.                       
                                                                               
If your file does not fit one of these two descriptions, or if it is similar   
to the standard .COM file description but has segment fixups, the following   
message is displayed:                                                         
                                                                               
File cannot be converted                                                       
                                                                               
This message is also displayed if the file is not a valid .EXE file.           
                                                                               
See the IBM Macro Assembler manual for a comparison of .EXE and .COM file     
structures.  Skeleton structures for .EXE files and .COM files are provided   
on the MASM diskette.
</PRE>


==Chapter 10==
==The Utilities Diskette==
<PRE>
A utilities diskette is included with this book. It contains a listing of the following utilities, and the description of each utility, to help
CHAPTER 10.  DEBUGGING A PROGRAM 32
programmers develop an application program:
The DEBUG Utility 37
*DEBUG.COM - A utility to isolate and determine errors in executable programs.
Starting the DEBUG.COM Program 46
*EXE2BIN.EXE - A utility to convert executable file formats (.EXE) to .COM formats to make them more compact and, therefore, load more quickly.
Entering Commands at the DEBUG Prompt 67
*LIB.EXE - A utility that allows the programmer to build and edit object libraries.
DEBUG Command Summary 103
*LINK.EXE - A utility to translate object code to executable code.
The DEBUG Work Space 181
*VDISK.ASM - A fully documented programming example of a device driver. However, this example does not reflect the current level of VDISK.SYS.
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==
==Links==
<PRE>
*[https://archive.org/download/bitsavers_ibmpcdos15lReferenceJul88_10507385/15F0256_DOS_4.0_Technical_Reference_Jul88.pdf PDF]
CHAPTER 11. WRITING AN INSTALLABLE DEVICE DRIVER 26
*{{L-IBMAnnUS|ZP88-0364}} 1988-07-20 - Disk Operating System Version 4.00
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                             
[[Category:DOS Documentation]]
                                                                               
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>
 
[[Category:DOS Books]]

Latest revision as of 23:58, 12 August 2023

The DOS 4.00 Technical Reference and Application Programming is an additional purchase item written for programmer's who develop applications for IBM Personal Computers and Personal System/2.

15F0256
1988

It consists of the following materials:

  • DOS Version 4.00 Technical Reference
  • DOS Version 4.00 Technical Quick Reference
  • Conditions of Use Statement
  • 3.5" (720KB) DOS Utilities Diskette
  • 5.25" (360KB) DOS Utilities Diskette

Contents

  1. Introduction
  2. Accessing Disks
  3. Accessing Files With File Handles
  4. Accessing Files Using File Control Blocks
  5. Managing Device I/O
  6. Controlling Processes
  7. Creating OBJECT CODE LIBRARIES
  8. Creating an Executable File
  9. Converting File Formats
  10. Debugging a Program
A. DOS 4.00 Interrupts
B. DOS 4.00 Function Calls
C. I/O Control for Devices (IOCTL)
D. Expanded Memory Support

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.

Links

  • PDF
  • ZP88-0364 1988-07-20 - Disk Operating System Version 4.00