15F0256_DOS_4.0_Technical_Reference_Jul88 15F0256 DOS 4.0 Technical Reference Jul88

15F0256_DOS_4.0_Technical_Reference_Jul88 15F0256_DOS_4.0_Technical_Reference_Jul88

User Manual: 15F0256_DOS_4.0_Technical_Reference_Jul88

Open the PDF directly: View PDF .
Page Count: 446

Download
Open PDF In Browser	View PDF

International Business Machines Corporation Armonk, New York 10504
IBM Program License Agreement
BEFORE OPENING THIS PACKAGE, YOU SHOULD CAREFULLY READ
THE FOLLOWING TERMS AND CONDITIONS. OPENING THIS
PACKAGE INDICATES YOUR ACCEPTANCE OF THESE TERMS AND
CONDITIONS. IF YOU DO NOT AGREE WITH THEM, YOU SHOULD
PROMPTLY RETURN THE PACKAGE UNOPENED AND YOUR MONEY
WILL BE REFUNDED.
This is a license agreement and not an
agreement for sale. I BM owns, or has
licensed from the owner, copyrights in
the Program. You obtain no rights other
than the license granted you by this
Agreement. Title to the enclosed copy of
the Program, and any copy made from it,
is retained by IBM. IBM licenses your
use of the Program in the United States
and Puerto Rico. You assume all responsibility for the selection of the Program
to achieve your intended results and for
the installation of, use of, and results
obtained from, the Program.
The Section in the enclosed documentation entitled "License Information"
contains additional information concerning the Program and any related
Program Services.
LICENSE
You may:
1) use the Program on only one
machine at anyone time, unless
permission to use it on more than
one machine at anyone time is
granted in the License Information
(Authorized Use);
2) make a copy of the Program for
backup or modification purposes
only in support of your Authorized
Use. However, Programs marked
"Copy Protected" limit copying;
3) modify the Program and/or merge it
into another program only in support
of your Authorized Use; and
4) transfer possession of copies of the
Program to another party by transferring this copy of the IBM Program
License Agreement, the License
Information, and all other documentation along with at least one
complete, unaltered copy of the
Program. You must, at the same
time, either transfer to such other

84X 1712

party or destroy all your other copies
of the Program, including modified
copies or portions of the Program
merged into other programs. Such
transfer of possession terminates
your license from IBM. Such other
party shall be licensed, under the
terms of this Agreement, upon
acceptance of this Agreement by its
initial use of the Program.
You shall reproduce and include the
copyright notice(s) on all such copies of
the Program, in whole or in part.
You shall not:
1) use, copy, modify, merge, or transfer
copies of the Program except as
provided in this Agreement;
2) reverse assemble or reverse compile
the Program;
and/or
3) sublicense, rent, lease, or assign the
Program or any copy thereof.
LIMITED WARRANTY
Warranty details and limitations are
described in the Statement of Limited
Warranty which is available upon request
from IBM, its Authorized Dealer or its
approved supplier and is also contained
in the License Information. IBM provides
a three-month limited warranty on the
media for all Programs. For selected
Programs, as indicated on the outside of
the package, a limited warranty on the
Program is available. The applicable
Warranty Period is measured from the
date of delivery to the original user as
evidenced by a receipt.
Certain Programs, as indicated on the
outside of the package, are not warranted
and are provided "AS IS."

Continued on inside back cover.

First Edition (July 1988)
The following paragraph does not apply to the United Kingdom or any
country where such provisions are Inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES
THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer
of express or implied warranties in certain transactions, therefore,
this statement may not apply to you.
This publication could include technical inaccuracies or typographical
errors. Changes are periodically made to the information herein;
these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s)
and/or the program(s) described in this publication at any time.
It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming,
or services that are not announced in your country. Such references
or information must not be construed to mean that IBM intends to
announce such IBM products, programming, or services in your
country.
Requests for technical information about IBM products should be
made to your IBM Authorized Dealer or your IBM Marketing Representative.

DOS 4.00 Library
Getting Started With DOS 4.00

The first part of this book provides information you need to install DOS 4.00 and
supplements the online information in
the SELECT program. The second part
introduces you to the DOS Shell.
Using DOS 4.00

By using examples, this book explains
how to manage your information from
the command prompt, how to change the
configuration of your system, and how to
create and change batch fi les.
DOS 4.00 Command Reference
This book, an additional purchase item,
provides detailed information on the
commands used in DOS 4.00 and contains tables relating tasks to these commands.
DOS 4.00 Technical Reference and
Application Programming

This book, an additional purchase item,
is written for programmers who develop
applications for IBM Personal Computers and Personal System/2®.

Personal System/2 is a registered trademark of the International Business Machines Corporation.

III

Preface
Audience
This book is written for programmers who develop applications for
IBM Personal Computers and Personal System/2® 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.

Personal System/2 is a registered trademark of the International Business Machines Corporation.
y

Contents
Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Organization of this Book . . . . . . . . . . . . . . . . . . . . . . . . . . .
New DOS 4.00 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Utilities Diskette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Minimum Hardware Configuration . . . . . . . . . . . . . . . . . . . . .

1-1
1-1
1-2
1-2
1-3

Part 1. Writing Programs
Chapter 2. Accessing Disks . . . . . . . . . . . . . . . . . . . . . . . . .
The Disk Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Boot Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The File Allocation Table (FAT) . . . . . . . . . . . . . . . . . . . . .
The Disk Di rectory . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Data Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessi ng the Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reading and Writing Data Directly to the Disk . . . . . . . . . . . . .
Requesting Drive and Disk Information .......... . . . . . . . .

2-1
2-1
2-1
2-2
2-3
2-4
2-4
2-5
2-5

Chapter 3. Accessing Flies with File Handles . . . . . . . . . . . . .
Filenames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Special File Handles . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Reading and Writing Data to a File . . . . . . . . . . . . . . . . . . . .
Requesting and Specifying File Attributes . . . . . . . . . . . . . . . .
Accessing Subdirectories . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Finding Files in Directories . . . . . . . . . . . . . . . . . . . . . . . . . .
Requesting and Specifying National Language Support (NLS)
Controlling Network Operations . . . . . . . . . . . . . . . . . . . . . .

3-1
3-1
3-2
3-3
3-3
3-4
3-4
3-7
3-7
3-8
3-8

Chapter 4. Accessing Flies Using File Control Blocks .......
The File Control Block (FCB) . . . . . . . . . . . . . . . . . . . . . . . .
The Extended FCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Disk Transfer Area (DTA) . . . . . . . . . . . . . . . . . . . . . .
Accessing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Accessing Sequential Records . . . . . . . . . . . . . . . . . . . . . . .
Accessi ng Random Records . . . . . . . . . . . . . . . . . . . . . . . . .
Finding Files in Directories . . . . . . . . . . . . . . . . . . . . . . . . . .

4-1
4-1
4-5
4-5
4-6
4-7
4-8
4-8

vII

Chapter 5. Managing Device 1/0 . . . . . . . . . . . . . . . . . . . . . .
Managing Display 110 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Keyboard 110 . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Managing Miscellaneous 110 . . . . . . . . . . . . . . . . . . . . . . . .
Managing File System Activities . . . . . . . . . . . . . . . . . . . . . .
Accessing the System Device Drivers' Control Channel ......
Reading and Writing Data in Binary and ASCII Modes ......

5-1
5-1
5-2
5-2
5-3
5-3
5-5

Chapter 6. Controlling Processes . . . . . . . . . . . . . . . . . . . . . 6-1
Allocating Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1
DOS 4.00 Memory Management . . . . . . . . . . . . . . . . . . . . 6-1
The DOS 4.00 Memory Map . . . . . . . . . . . . . . . . . . . . . . . 6-2
Identifying a Program at Load Time . . . . . . . . . . . . . . . . . . . . 6-4
The Program Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-4
Loading and Executing Overlays . . . . . . . . . . . . . . . . . . . . . . 6-7
The Parameter Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7
Terminating a Program/Subprogram . . . . . . . . . . . . . . . . . . . 6-8
Loading an Overlay without Executing It . . . . . . . . . . . . . . . . 6-10
Calling a Command Processor . . . . . . . . . . . . . . . . . . . . . . 6-10
Responding to Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-11
Responding to a Control-Break Action . . . . . . . . . . . . . . . . . 6-12
Requesting and Specifying the System Date and Time ...... 6-13
Requesting and Specifying the Interrupt Vectors .......... 6-13

Part 2. Using the Programming Utilities
Chapter 7. Creating Object Code Libraries . . . . . . . . . . . . . . . 7-1
The IBM Library Manager/2 . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
Starting the LlB.EXE Utility . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Entering Input at the Command Line . . . . . . . . . . . . . . . . . 7-5
Using a Response File . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
Creating and Maintaining Libraries . . . . . . . . . . . . . . . . . . . . 7-9
Creating a Library File . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-9
Modifying a Library File . . . . . . . . . . . . . . . . . . . . . . . . . 7-10
Combining Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12
Creating a Cross-Reference Listing . . . . . . . . . . . . . . . . . 7-12
Performing Consistency Checks . . . . . . . . . . . . . . . . . . . 7-13
Setting the Library Page Size . . . . . . . . . . . . . . . . . . . . . 7-13
Library Manager Error Messages . . . . . . . . . . . . . . . . . . . . 7-15
Chapter 8. Creating an Executable File . . . . . . . . . . . . . . . . . 8-1
The IBM Linker/2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

vIII

Starting the LlNK.EXE Program . . . . . . . . . . . . . . . . . . . . . . . 8-1
Entering LINK Input at the Command Line . . . . . . . . . . . . . . 8-6
Using a Response File to Supply LINK Input ............ 8-8
Using Linker Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-11
Preparing Files for CodeView ICODEVIEW . . . . . . . . . . . . . . 8-13
Reserving Paragraph Space ICPARMAXALLOC ........... 8-14
Ordering Segments IDOSSEG . . . . . . . . . . . . . . . . . . . . . . . 8-15
Controlling Data Loading IDSALLOCATE . . . . . . . . . . . . . . . 8-16
Packing Executable Files IEXEPACK . . . . . . . . . . . . . . . . . . 8-17
Viewing the Options List IHELP . . . . . . . . . . . . . . . . . . . . . . 8-18
Controlling Run File Loading IHIGH . . . . . . . . . . . . . . . . . . . 8-19
Displaying LINK-Time Information IINFORMATION ......... 8-20
Copying Line Numbers to the Map File ILiNENUMBERS ..... 8-21
Producing a Public Symbol M~p IMAP . . . . . . . . . . . . . . . . . 8-22
Ignoring Default Libraries INODEFAULTLIBRARYSEARCH
8-23
Preserving Compatibility INOGROUPASSOCIATION ........ 8-24
Preserving Lowercase INOIGNORECASE . . . . . . . . . . . . . . . 8-25
Setting the Overlay Interrupt IOVERLAYINTERRUPT ........ 8-26
Pausing to Change Disks IPAUSE . . . . . . . . . . . . . . . . . . . . 8-27
Setting the Maximum Number of Segments ISEGMENTS ..... 8-29
Setting the Stack Size ISTACK . . . . . . . . . . . . . . . . . . . . . . 8-30
Reading the Map File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-31
Creating an Overlaid Version of Your Program ........... 8-32
Specifying an Overlay Structure to LINK . . . . . . . . . . . . . . 8-32
How LINK Formats the .EXE File . . . . . . . . . . . . . . . . . . . . . 8-33
Ordering Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-33
Segment Combine-Types . . . . . . . . . . . . . . . . . . . . . . . . 8-34
Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-35
Instruction and Data Reference Errors . . . . . . . . . . . . . . . 8-35
Linker Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-37
Linker Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-48
Chapter 9. Converting File Formats .. . . . . . . . . . . . . . . . . . .
The EXE2BIN.EXE Utility . . . . . . . . . . . . . . . . . . . . . . . . . . .
Entering Input to EXE2BIN . . . . . . . . . . . . . . . . . . . . . . . . . .
Two Types of Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . .
Device Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Standard .COM File . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 10. Debugging a Program . . . . . . . . . . . . . . . . . . .
The DEBUG Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
Starting the DEBUG.COM Program . . . . . . . . . . . . . . . . . . .
Entering Commands at the DEBUG Prompt . . . . . . . . . . . . . .

9-1
9-1
9-1
9-2
9-3
9-3
10-1
10-1
10-1
10-2
Ix

DEBUG Command Summary . . . . . . . . . . . . . . . . . . . . ..
The DEBUG Work Space . . . . . . . . . . . . . . . . . . . . . . . . . .
A (Assemble) Command . . . . . . . . . . . . . . . . . . . . . . . . . .
C (Compare) Command . . . . . . . . . . . . . . . . . . . . . . . . . . .
D (Dump) Command . . . . . . . . . . . . . . . . . . . . . . . . . . . .
E (Enter) Command . . . . . . . . . . . . . . . . . . . . . . . . . . . ..
F (Fill) Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
G (Go) Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
H (Hexarithmetic) Command . . . . . . . . . . . . . . . . . . . . . . .
I (Input) Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
l (load) Com mand . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
M (Move) Command . . . . . . . . . . . . . . . . . . . . . . . . . . . .
N (Name) Command . . . . . . . . . . . . . . . . . . . . . . . . . . . .
o (Output) Command . . . . . . . . . . . . . . . . . . . . . . . . . . ..
P (Proceed) Command . . . . . . . . . . . . . . . . . . . . . . . . . ..
Q (Quit) Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
R (Register) Command . . . . . . . . . . . . . . . . . . . . . . . . . .
S (Search) Command . . . . . . . . . . . . . . . . . . . . . . . . . . .
T (Trace) Command . . . . . . . . . . . . . . . . . . . . . . . . . . . .
U (Unassemble) Command . . . . . . . . . . . . . . . . . . . . . . . .
W (Write) Command . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XA (EMS Allocate) Command . . . . . . . . . . . . . . . . . . . . . .
XD (EMS Deallocate) Command . . . . . . . . . . . . . . . . . . . .
XM (EMS Map) Command . . . . . . . . . . . . . . . . . . . . . . . .
XS (EMS Status) Command . . . . . . . . . . . . . . . . . . . . . . .
DEBUG Error Messages .. . . . . . . . . . . . . . . . . . . . . . . ..

10-3
10-4
10-6
10-9
10-11
10-14
10-17
10-19
10-22
10-23
10-24
10-27
10-29
10-31
10-32
10-33
10-34
10-38
10-40
10-42
10-45
10-48
10-49
10-50
10-51
10-52

Chapter 11. Writing an Installable Device Driver ..........
Types of Device Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . .
Character Device Drivers . . . . . . . . . . . . . . . . . . . . . . . .
Block Device Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . .
How DOS 4.00 Installs Device Drivers . . . . . . . . . . . . . . . . .
The Basic Parts of a Device Driver . . . . . . . . . . . . . . . . . . .
The Device Driver Header . . . . . . . . . . . . . . . . . . . . . . .
The Strategy Routine . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Interrupt Routines . . . . . . . . . . . . . . . . . . . . . . . . . .
How DOS 4.00 Passes a Request . . . . . . . . . . . . . . . . . . . . .
Responding to Requests . . . . . . . . . . . . . . . . . . . . . . . . . .
Initialization Request . . . . . . . . . . . . . . . . . . . . . . . . . .
Media Check Request . . . . . . . . . . . . . . . . . . . . . . . . .
Build BPB Request . . . . . . . . . . . . . . . . . . . . . . . . . . .
Input and Output Requests . . . . . . . . . . . . . . . . . . . . . .
Nondestructive Input No Wait Request . . . . . . . . . . . . . .

11-1
11-1
11-1
11-1
11-2
11-3
11-4
11-6
11-7
11-7
11-9
11-11
11-13
11-16
11-20
11-22

Character Input and Output Status Requests ..........
Character Input and Output Flush Requests ...........
Open and Close Requests . . . . . . . . . . . . . . . . . . . . . .
Removable Media Request . . . . . . . . . . . . . . . . . . . . . .
Generic 10CTL Request . . . . . . . . . . . . . . . . . . . . . . . .
Get Logical Device Request . . . . . . . . . . . . . . . . . . . . .
Set Logical Device Request . . . . . . . . . . . . . . . . . . . . .
CLOCK$ Device Driver Example . . . . . . . . . . . . . . . . . . . .

11-23
11-24
11-25
11-25
11-27
11-28
11-28
11-29

Part 3. Appendixes
Appendix A. DOS 4.00 Interrupts . . . . . . . . . . . . . . . . . . .
20H Program Terminate . . . . . . . . . . . . . . . . . . . . . . . . . .
21 H Function Request . . . . . . . . . . . . . . . . . . . . . . . . . . .
22H Terminate Address . . . . . . . . . . . . . . . . . . . . . . . . . .
23H Ctrl-8reak Exit Address . . . . . . . . . . . . . . . . . . . . . . .
24H Critical Error Handler Vector
25H/26H Absol ute Disk Read/Write
27H Terminate but Stay Resident . . . . . . . . . . . . . . . . . . . .
28H - 2EH Reserved for DOS 4.00 . . . . . . . . . . . . . . . . . . .
2FH Multiplex Interrupt . . . . . . . . . . . . . . . . . . . . . . . . . .
30H-3FH Reserved for DOS 4.00 . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.

.
.
.
.

A-1
A-1
A-1
A-2
A-2
A-3
A-7
A-9
A-10
A-10
A-17

Appendix B. DOS 4.00 Function Calls . . . . . . . . . . . . . . . .
Usi ng DOS 4.00 Function Calls . . . . . . . . . . . . . . . . . . . . .
Program Code Fragments . . . . . . . . . . . . . . . . . . . . . .
.COM Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DOS 4.00 Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Responding to Errors . . . . . . . . . . . . . . . . . . . . . . . . . . .
Extended Error Codes . . . . . . . . . . . . . . . . . . . . . . . . .
OOH - Program Terminate . . . . . . . . . . . . . . . . . . . . . . .
01 H - Console Input with Echo . . . . . . . . . . . . . . . . . . . .
02H - Display Ou~put . . . . . . . . . . . . . . . . . . . . . . . . . .
03H - Auxiliary Input . . . . . . . . . . . . . . . . . . . . . . . . . .
04H - Auxiliary Output . . . . . . . . . . . . . . . . . . . . . . . . .
05H - Printer Output . . . . . . . . . . . . . . . . . . . . . . . . . . .
06H - Direct Console I/O . . . . . . . . . . . . . . . . . . . . . . . .
07H - Di rect Console Input Without Echo . . . . . . . . . . . . .
08H - Console Input Without Echo . . . . . . . . . . . . . . . . .
09H - Display String . . . . . . . . . . . . . . . . . . . . . . . . . . .
OAH - 8uffered Keyboard Input . . . . . . . . . . . . . . . . . . .
08H - Check Standard Input Status . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

8-1
8-3
8-4
8-4
8-4
8-6
8-7
8-12
8-13
8-14
8-15
8-16
8-17
8-18
8-19
8-20
8-21
8-22
8-23

OCH ODH OEH OFH 10H 11H 12H 13H 14H 15H 16H 17H 19H 1AH 18H 1CH 21H 22H 23H 24H 25H 26H 27H 28H 29H 2AH 28H 2CH 2DH 2EH 2FH 30H 31H 33H 35H 36H 38H 39H 3AH 38H 3CH 3DH 3EH xII

Clear Keyboard 8uffer and Invoke a Keyboard Function
Disk Reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Select Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Open File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Close File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Search for First Entry . . . . . . . . . . . . . . . . . . . . . . .
Search for Next Entry . . . . . . . . . . . . . . . . . . . . . . .
Delete File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sequential Read . . . . . . . . . . . . . . . . . . . . . . . . . .
Sequential Write . . . . . . . . . . . . . . . . . . . . . . . . . .
Create File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rename File . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Current Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Disk Transfer Address . . . . . . . . . . . . . . . . . . .
Allocation Table Information . . . . . . . . . . . . . . . . . .
Allocation Table Information for Specific Device
Random Read . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Random Write .......... . . . . . . . . . . . . . . . . . .
File Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Relative Record Field . . . . . . . . . . . . . . . . . . . .
Set Interrupt Vector . . . . . . . . . . . . . . . . . . . . . . . .
Create New Program Segment . . . . . . . . . . . . . . . .
Random 810ck Read . . . . . . . . . . . . . . . . . . . . . . .
Random 810ck Write . . . . . . . . . . . . . . . . . . . . . . .
Parse Filename .. . . . . . . . . . . . . . . . . . . . . . . . . .
Get Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Get Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set/Reset Verify Switch . . . . . . . . . . . . . . . . . . . . .
Get Disk Transfer Address (DTA) . . . . . . . . . . . . . . .
Get DOS Version Number . . . . . . . . . . . . . . . . . . . .
Terminate Process and Remain Resident .........
Get/Set System Value . . . . . . . . . . . . . . . . . . . . . .
Get Interrupt Vector ..... : . . . . . . . . . . . . . . . . . .
Get Disk Free Space . . . . . . . . . . . . . . . . . . . . . . .
Get or Set Country Dependent Information ........
Create Subdirectory (MKDIR) . . . . . . . . . . . . . . . . .
Remove Subdirectory (RMDIR) . . . . . . . . . . . . . . . .
Change the Current Directory (CHOIR) . . . . . . . . . . .
Create a File (CREAT) . . . . . . . . . . . . . . . . . . . . . .
Open a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Close a File Handle . . . . . . . . . . . . . . . . . . . . . . . .

8-24
8-25
8-26
8-27
8-29
8-30
8-32
8-34
8-35
8-36
8-37
8-38
8-40
8-41
8-42
8-43
8-44
8-46
8-48
8-49
8-50
8-51
8-52
8-54
8-56
8-58
8-59
8-60
8-61
8-62
8-63
8-64
8-65
8-66
8-68
8-69
8-71
8-74
8-75
8-76
8-77
8-78
8-85

3FH 40H 41H 42H 43H 44H 45H 46H 47H 48H 49H 4AH 48H 4CH 4DH 4EH 4FH 54H 56H 57H 59H 5AH 58H 5CH 5EOOH
5E02H
5E03H
5F02H
5F03H
5F04H
62H 65H 66H 67H 68H 6CH -

Read from a File or Device . . . . . . . . . . . . . . . . . . . 8-86
Write to a Fi Ie or Device . . . . . . . . . . . . . . . . . . . . . 8-87
Delete a File from a Specified Directory (UNLINK)
8-89
Move File Read Write Pointer (LSEEK) ........... 8-90
Change File Mode (CHMOD) . . . . . . . . . . . . . . . . . . 8-92
110 Control for Devices . . . . . . . . . . . . . . . . . . . . . . 8-94
Duplicate a File Handle (DUP) . . . . . . . . . . . . . . . . . 8-95
Force a Duplicate of a Handle (FORCDUP) ........ 8-96
Get Current Directory . . . . . . . . . . . . . . . . . . . . . . . 8-97
Allocate Memory . . . . . . . . . . . . . . . . . . . . . . . . . . 8-98
Free Allocated Memory . . . . . . . . . . . . . . . . . . . . . 8-99
Modify Allocated Memory 810cks (SET8LOCK) .... 8-100
Load or Execute a Program (EXEC) ............ 8-101
Terminate a Process (EXIT) . . . . . . . . . . . . . . . . . 8-105
Get Return Code of a Subprocess (WAIT) ........ 8-106
Find First Matching File (FIND FIRST) ........... 8-107
Find Next Matching File (FIND NEXT) ........... 8-109
Get Verify Setting . . . . . . . . . . . . . . . . . . . . . . . . 8-110
Rename a File . . . . . . . . . . . . . . . . . . . . . . . . . . 8-111
Get/Set File's Date and Time . . . . . . . . . . . . . . . .. 8-112
Get Extended Error . . . . . . . . . . . . . . . . . . . . . . . 8-113
Create Unique File . . . . . . . . . . . . . . . . . . . . . . . 8-115
Create New File . . . . . . . . . . . . . . . . . . . . . . . . . 8-117
Lock/Unlock File Access . . . . . . . . . . . . . . . . . . . 8-118
- Get Machine Name . . . . . . . . . . . . . . . . . . . . . 8-121
- Set Printer Setup . . . . . . . . . . . . . . . . . . . . . . . 8-122
- Get Printer Setup . . . . . . . . . . . . . . . . . . . . . . . 8-123
- Get Redirection List Entry . . . . . . . . . . . . . . . . . 8-124
- Redirect Device . . . . . . . . . . . . . . . . . . . . . . . . 8-126
- Cancel Redirection . . . . . . . . . . . . . . . . . . . . . . 8-129
Get Program Segment Prefix Address .......... 8-131
Get Extended Country Information . . . . . . . . . . . . . 8-132
Get/Set Global Code Page . . . . . . . . . . . . . . . . . . 8-135
Set Handle Count . . . . . . . . . . . . . . . . . . . . . . . . 8-136
Commit File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-137
Extended OpenlCreate . . . . . . . . . . . . . . . . . . . . 8-138

Appendix C. 1/0 Control for Devices (IOCtl) . . . . . . . . . . . . .
44H - 110 Control for Devices (IOCtl) . . . . . . . . . . . . . . . . .

C-1
C-3

Appendix D. Expanded Memory Support

0-1

Index

...............

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . X-1
xiII

xlv

Chapter 1. Introduction
This chapter provides information about this book, including the
following:
•
•
•
•

Organization of the book for quick information retrieval
New and enhanced DOS 4.00 services
Contents of the utilities diskette
Minimum hardware configuration.

Organization of this Book
This book is organized by logical application program development
stages necessary to develop an application program on DOS 4.00.
You must:
•
•
•
•
•
•

Write the source code for the program
Translate the source code to executable code
Load and execute the program
Debug the program
Create object code libraries (optional)
Convert your file formats (optional).

In addition, the book tells how to make best use of the operating
system by writing your own device driver or by using the system
extensions.
Each chapter describes a particular subject. You do not need to read
the entire book to create programs or solve problems. Key topics
also can be found by referring to the index and the table of contents.
The appendixes contain reference information for quick retrieval.
They contain the entire numerical list of DOS 4.00 services, including
interrupts, function calls, and device driver services.
The Technical Quick Reference contains abbreviated information
about interrupts. Function calls are listed, along with input/output
information and error codes.

1-1

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 DiskeHe
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.

LlB.EXE

A utility that allows the programmer to build
and edit object libraries.

LlNK.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.

1-2

Minimum Hardware Configuration
DOS 4.00 supports the following family of IBM Personal Computers
and Personal System/2 computers:
The
The
The
The
The
The
The
The
The
The

IBM
IBM
IBM
IBM
IBM
IBM
IBM
IBM
IBM
IBM

Personal Computer
Personal Computer XTTM
Personal Computer)(TTM Model 286 1
Personal Computer AT® (all versions)2
PC Convertible
Personal System/2® Model 25 (all versions)
Personal System/2® Model 30 (all versions)
Personal System/2® Model 50 (all versions)
Personal System/2® Model 60 (all versions)
Personal System/2® Model 80 (all versions).

Note: DOS 4.00 does not support the IBM PCjr.
The minimum memory requirement is 256KB.

Personal Computer XT is a trademark of the International Business
Machines Corporation.

Personal Computer AT and Personal System/2 are registered trademarks
of the International Business Machines Corporation.

1·3

1-4

Part 1. Writing Programs

Chapter 2. Accessing Disks
This chapter provides the necessary guide and system architecture
information to help you successfully complete the following tasks:
• Accessing the disk
• Formatting the disk
• Reading and writing data to the disk.

The Disk Format
All disks and diskettes formatted by DOS 4.00 are created with a
sector size of 512 bytes. DOS 4.00 is formatted on a diskette or on a
designated partition of a fixed disk in the following order:
DOS 4.00
Component

Size

The boot record

1 sector

The first copy of the File Allocation Table (FAT)

Variable

The second copy of the FAT

Variable

The disk root directory

Variable

The data area

Variable

The Boot Record
The DOS 4.00 FORMAT command creates the boot record. For
diskettes, the boot record resides on track 0, sector 1, side O. While
for fixed disks, it resides at the starting sector of the partition.
Accessing any media (diskette or fixed disk) that does not have a
valid boot record causes an error message.

2-1

The File Allocation Table (FAT)
The File Allocation Table (FAT) occupies the sectors immediately following the boot record. If the FAT is larger than one sector, the
sectors occupy consecutive sector numbers.
The FAT keeps track of the physical location of all files on the disk. If
the FAT cannot be read because of a disk error, the contents of the
files cannot be located. For this reason, two copies of the FAT are
written on the disk.
DOS 4.00 uses the FAT to allocate disk space to a file, one cluster at a
time. The FAT consists of a 12-bit entry (1.5 bytes) or a 16-bit entry (2
bytes) for each cluster on the disk. On a fixed disk, the number of
sectors for each cluster are determined by the size of the disk. DOS
4.00 determines whether to create a 12-bit or 16-bit FAT by calculating the number of a-sector clusters that can occupy the space on
the disk. If the number of clusters is less than 4086, a 12-bit FAT is
created. If it is greater, a 16-bit FAT is created.
Using the following formula, you can determine the number of sectors
on a disk:
TS=SPT * H * C.
TS == the total number of sectors on the disk.
SPT == the number of sectors per track or per cylinder.

H
C

the number of heads.
the number of cylinders.

The number of sectors on a 10MB IBM fixed disk, for example, is
20740 (17 * 4 * 305).

2·2

The first two entries in the FAT are not used to map data. They indicate the size and format of the disk. The first byte of the FAT designates one of the following:
Hex
Value

Meaning

Double-sided, a sectors per track diskette

Single-sided, a sectors per track diskette

Double-sided, 9 sectors per track diskette

Single-sided, 9 sectors per track diskette

Double-sided, 15 sectors per track diskette (1.2 MB)

Double-sided, 9 sectors per track diskette (720 KB)

Fixed disk

Others

The first two FAT entries indicate the size and format of the disk. The
second and third bytes of the FAT contain the value FFH. The fourth
byte, used by 16-bit FATs only, contains the value FFH.
The maximum size 16-bit FAT supported by DOS 4.00 for media
greater than 32MB is 64KB entries, or 12aKB of space on the disk.
This is an increase in size from the IBM PC DOS 3.30 limit of 16KB
entries.

The Disk Directory
When the FORMAT command is issued, it builds the root directory for
all disks. If the disk is formatted with the IS option, the DOS 4.00
system files, (IBMBIO.COM, IBMDOS.COM, and

2-3

COMMAND.COM), are added to the disk. The following seven
formats are used for 5.25-inch diskettes and 3.5-inch diskettes:

Sides

FAT
Sectorsl Size
DIR
DIR
Sectorsl
Track
Sectors Sectors Entries Cluster

1 (5.25)

2 (5.25)

112

1 (5.25)

2 (5.25)

112

2 (5.25)

224

2 (3.5)

112

2 (3.5)

224

The Data Area
Data files and subdirectories are stored in the last and largest part of
a disk. Space is allocated as it is needed, a cluster at a time. This
allocation method permits the most efficient use of disk space. As
clusters become available, space can be allocated for new files.

Accessing the Disk
Most interrupt 21H functions can be used to access a disk. Five other
functions can be used to perform disk-related actiVity.

Activity

Function
Number

Resetting the disk and flushing the file buffer

ODH

Selecting the default disk drive

OEH

Accessing the current disk

19H

Requesti ng the amount of free space on the disk

36H

Determining the drive at start-up time

33H

Reading and Writing Data Directly to the Disk
DOS 4.00 provides two interrupts, 25H and 26H, to read and write data
to a disk.

Activity

Interrupt
Number

Reading from specified disk sectors

25H

Writing to specified disk sectors

26H

Requesting Drive and Disk Information
Information on disks and drives can be requested by using the following functions:

Activity

Function
Number

Requesting the current drive number

19H

Requesting disk allocation information

1BH

Requesting disk allocation information about the specified
drive

1CH

2-5

2-6

Chapter 3. Accessing Files with File
Handles
The information necessary to complete the following tasks is provided in this chapter:
•
•
•
•
•

Reading and writing data to a file
Requesting and specifying file attributes
Accessing directories
Searching for files in directories
Requesting and specifying National Language Support (NLS).

DOS 4.00 provides nine functions within interrupt 21 H to create, open,
close and delete a file.

Activity

Function
Number

Creating a new file or replaCing. an old file

3CH

Opening a file

3DH

Closing a file handle

3EH

Deleting a file

41H

Renaming a file

56H

Creating a new file with a unique name

5AH

Creating a new file

5BH

Locki ng and unlocki ng read/write access to regions of a
file

5CH

Creating and opening a file with extended parameters

6CH

Filenames
To name a file, the application program supplies a pointer to an
ASCIIZ string giving the name and location of the file. A filename

3-1

contains an optional drive letter, path, and/or file specification terminated with a hexadecimal 0 byte. Following is an example of a
filename string:
'B:\LEVEL1\LEVEL2\FILE1',e

The maximum size of a filename is 128 bytes, including the drive,
colon, path, name, and null terminator. All function calls that accept
path names accept a forward slash (/) or backslash (\) as path separator characters.

File Handles
The open or create function calls return a 16-bit value called a file
handle. To perform file I/O, a program uses the file handle to reference the file. Once a file is opened, the program no longer needs to
maintain the ASCIIZ string pointing to the file. DOS 4.00 keeps track
of the location of the file, regardless of which directory is current.

Activity

Function
Number

Specifying an additional file handle for a file

45H

Pointing the existing file handle to another file

46H

Specifying the number of open file handles

67H

The number of file handles that can be open at one time by all processes can be specified with the FILES command in CONFIG.SYS.
There are 20 default handles available to a Single process. All
handles inherited by a process can be redirected.
Each open handle is associated with a Single file or device, but
several handles can reference the same file or device. Thus, the
maximum handle limit can exceed the number specified with the
FILES command.

3-2

Special File Handles
DOS 4.00 provides five special file handles for use by application programs. The handles are:
OOOOH Standard input device (STDIN)
0001 H Standard output device (STDOUT)
0002H Standard error device (STDERR)
0003H Standard auxiliary device (STDAUX)
0004H Standard printer device (STDPRN)
File handles associated with standard devices do not need to be
opened by a program, but a program can close them. STDIN should
be treated as a read-only file. STDOUT and STDERR should be
treated as write-only files. STDIN and STDOUT can be redirected.
Function calls 01 H through OCH access the standard devices.
The standard device handles are useful for performing 1/0 to and
from the console device. For example, you can read input from the
keyboard using the read function call (3FH) and file handle OOOOH
(STDIN); you can also write output to the console screen with the
write function call (40H) and file handle 0001H (STDOUT).
If you want to prevent redirection of your output to STDOUT, you can
send it using file handle 0002H (STDERR). This facility also is useful
for error messages or prompts to the user.

Reading and Writing Data to a File
DOS 4.00 provides five functions to allow reading and writing to a file
or device, specifying the offset within a file at which the read or write
is to occur, and verifying the read-after-write state. The verification
operation, however, slows performance.

3-3

Activity

Function
Number

Reading from a file or device

3FH

Writing to a file or device

40H

Specifying the address (through the pointer) at which a
read or write is to occur

42H

Requesting the read-after-write state

54H

Specifying the read-after-write state

2EH

Requesting and Specifying File AHributes
While a file is being created, your program can specify certain attributes; for example, the date and time of creation and level of access.

Activity

Function
Number

Requesting and specifying a file's attributes

43H

Requesting and specifying a file's date and- time

57H

Accessing Subdirectories
Subdirectories, that is, directories other than the root directories, are
files. There is no limit to the number of subdirectory entries if the
physical media can accommodate them. All directory entries are 32
bytes long.
Note: Values are in hexadecimal.
The Filename
Bytes 0 through 7 represent the filename. The first byte of the
filename indicates the status of the filename. The status of a
filename can contain the following values:
OOH

Filename never used. To improve performance, used to limit
the length of directory searches.

05H

The first character of the filename has an E5H character.

E5H

Filename has been used, but the file has been erased.

3-4

2EH

The entry is for a directory. If the second byte is also 2EH, the
cluster field contains the cluster number of this directory's
parent directory. (Cluster number OOOOH if the parent directory
is the root directory.)
Any other character is the first-character of a filename.

Note: Byte offsets are in decimal.

The Filename Extension
Bytes 8 through 10 indicate the filename extension.
The File Attribute
Byte 11 indicates the file's attribute. The attribute byte is mapped as
follows:
01 H

Indicates a read-only file. An attempt to open the file for
output using function call 3DH or 6CH results in an error code
being returned.

02H

Indicates a hidden file. The file is excluded from normal directory searches.

04H

Indicates a system file. The file is excluded from normal directory searches.

08H

Indicates the entry contains the volume label in the first 11
bytes. The entry contains no other usable information and
may exist only in the root directory.

10H

Indicates the entry defines a subdirectory and is excluded from
normal directory searches.

20H

Indicates an archive bit. The bit is set ON when the file has
been written to and closed. It is used by the BACKUP and
RESTORE commands for determining whether the file has
been changed since it was created or last updated. This bit
can be used along with other attribute bits.
All other bits are reserved and must be O.

3·5

The File Creation/Last Changed Time

Bytes 22 and 23 contain the time when the file was created or last
updated. The time is mapped in the bits as follows:
23
> <
22
>
15 14 13 12 11 19 9 8 7 6 5 4 3 2 1 9

h h h

m mm mmm x x x x x

Where:
hh

mm
xx

= the binary number of hours (0-23)
= the binary number of minutes (0-59)
= the bi:nary number of two-second increments

The time is stored with the least significant byte first.
The File Creation Date

Bytes 24 and 25 contain the date when the file was created or last
updated. The mm/dd/yy are mapped in the bits as follows:
25
> <
24
>
15 14 13 12 11 19 9 8 7 6 5 4 3 2 1 9
y y y y y y y m m m m d d d d d

Where:

mm = 1-12
dd = 1-31
yy = 0-119 (1980-2099)
The date is stored with the least signifJoant byte fi rst.
The Starting Cluster Number

Bytes 26 and 27 contain the cluster number of the first cluster in the
file. The first cluster for data space on all fixed disks and diskettes is
cluster 002. The clu$ter number is stored with the least significant
byte fi rst.
<

3-8

> <

9 a 9 9 a 9 Gal a a a a 1

The File Size
Bytes 28 through 31 contain the file size in bytes. The first word contains the low-order part of the size. Both words are stored with the
least significant byte first.

Accessing Directories
DOS 4.00 provides four functions within interrupt 21H to create, move,
change or delete directories.

Activity

Function
Number

Removing a subdirectory

3AH

Creating a subdirectory

39H

Changing to another directory

3BH

Identifying the current directory

47H

Finding Files in Directories
DOS 4.00 provides two functions within interrupt 21H to search for the
first matching entry and the next matching entry.

Activity

Function
Number

Searching for the first matching entry

4EH

Searching for the next matching entry

4FH

3-7

Requesting and Specifying National Language
Support (NLS)
DOS 4.00 provides the following functions for NLS:

Activity

Function
Number

Specifying the current country

38H

Requesting the country dependent information

38H

Providing double-byte character set (DBCS) support

65H

Controlling Network Operations
Several DOS 4.00 function calls accept a network path as input if the
IBM PC Local Area Network is loaded. If network access is available,
further information is noted in the "Remarks" section under each relevant function call in Appendix B, "DOS 4.00 Function Calls" on
page B-1.
A network path consists of an ASCII string containing a computer
name,a directory path, and an optional filename. The network path
cannot contain a drive specifier. The path is terminated by a byte of
binary O's. Following is an example:
\\SERVERl\LEVELl\LEVEL2\FILEl

Many function calls that accept an ASCIIZ string as input accept a
network path. If you want to execute function 5BH (Create a New
File), for example, you must have Read/Write/Create or Write/Create
access to the directory to be able to create a file. If you have Read
Only or Write Only access and no Create access, you cannot create a
file in the directory. Two function calls that do not accept a network
path as input are Change Current Directory (3BH) and Find First
Matching File (4EH).

3-8

The following function calls are available to control network operations:

Activity

Function
Number

Locking and unlocking read/write access to a region of a
file

5CH

Writing all data from a file to a device

68H

Requesting the local computer 10

5EOOH

Specifying the printer setup string

5E02H

Requesting the printer setup string

5E03H

Requesting redirection

5F02H

Attaching to a redirect device

5F03H

Canceling redirection

5F04H

3-9

3-10

Chapter 4. Accessing Files Using File
Control Blocks
This chapter provides guide and system architecture information to
assist in performing the following tasks:
•
•
•
•
•

Accessing files
Accessing sequential records
Accessi ng random records
Finding files in directories
Requesting drive and disk information.

The File Control Block (FCB)
With few exceptions, a program should maintain files using File
Control Blocks (FCBs) only to run under DOS 1.10. Using FCBs, your
program is restricted to the use of function calls OOH through 2EH
only. File handles are the recommended method for accessing files.
One FCB maintained by your program and DOS 4.00 is required for
each open file. Your program must supply a pointer to the FCB and
fill in the appropriate fields required by specific function calls.
A program should not attempt to use the reserved fields in the FCB.
Bytes 0 through 15 and 32 through 36 must be set by the user
program. Bytes 16 through 31 are set by DOS 4.00 and must not be
changed by user programs.
An unopened FCB consists of the FCB prefix (if used), the drive
number, the filename, and the extensions appropriately specified. An
open FCB is one in which the remaining fields have been specified by
the create or open function calls.
All word fields are stored with the least significant byte first. For
example, a record length of 128 is stored as 80H at offset 14, and OOH
at offset 15. Figure 4-1 (The File Control Block) gives further explanation.

4-1

•
I

2.
~

c:
..,

~
.....

-I

..,

(1)

(")

Zeros

Drive

o:J

FCB
extension
Standard
FCB

Filename (8bytes) or Reserved device name

8
Curent block

Filename extension

..,:::J

Attribute

C.
CD

hexFF

(1)

::
en
CD

-7

cO·

0"
(")
~

Current
record

Random record
number (low part)

Random record
number (high part)
(offsets are In decimal)

Unshaded areas must be filled In by the using program.
Shaded areas are filled In by DOS and must not be modified.

Record size

The FeB is formatted as follows:
Drive Number

Byte 0 represents the drive number. For example, before an open 0
equals the default drive, 1 equals drive A, and 2 equals drive B. After
an open 0 equals drive A, 1 equals drive A, and 2 equals drive B.
The actual drive number replaces the 0 when a file is opened.
Filename

Bytes 1 through 8 represent the filename, left-justified with trailing
blanks. If a reserved device name such as LPT1 is specified here, do
not include the colon.
Filename Extension

Bytes 9 through 11 represent the filename extension, left-justified
with trailing blanks or all blanks.
Current Block Number

Bytes 12 through 13 represent the current block number relative to
the beginning of the file, starting with O. The 0 is set by the open
function call. A block consists of 128 records, each size specified in
the logical record size field. The current block number is used with
the current record field for sequential reads and writes.
Logical Record Size

Bytes 14 through 15 represent the logical record size in bytes. 80H is
set by the open function call. If you want to change the logical record
size from 80H, you can reset the value. DOS 4.00 uses the value to
determine locations in the file for all disk reads and writes.
File Size

Bytes 16 through 19 represent file size in bytes. In this two-word
field, the fi rst word is the low-order part of the size.

4-3

File Date
Bytes 20 through 21 represent the date the file was created or last
updated. The mmlddlyy are mapped in the bits as follows:
21
> <
20
>
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
y y y y y y y m m m m d d d d d
<

where:
mm is 1-12
dd is 1-31
yy is 0-119 (1980-2099)
Reserved
Bytes 22 through 31 are reserved.
Record Number In Block
Byte 32 represents the current relative record number (0-127) within
the current block. You must set this field before doing sequential
read and write operations to the diskette. This field is not initialized
by the open function call.
Record Number within File
Bytes 33 through 36 represent the record number relative to the
beginning of the file, starting with O. You must set this field before
doing random read and write operations to the diskette. This field is
not initialized by the open function call.
If the record size is less than 64 bytes, both words are used. If the
record size is more than 64 bytes, only the first 3 bytes are used.
Note that if you use the FCB at 5CH in the program segment, the last
byte of the FCB overlaps the first byte of the unformatted parameter
area.

4-4

The Extended FeB
The extended FCB is used to create or search in the disk directory for
files with special attributes. The extension adds a 7-byte prefix to the
FCB, formatted as follows:
Extended FeB
FCB byte -7 contains FFH to indicate an extended FCB.
Reserved
FCB bytes -6 to -2 are reserved.
File AHrlbute
FCB byte -1 represents an attribute byte. Function calls OOH through
2EH are valid for both the standard FCB and the extended FCB. If you
are using an extended FCB, the appropriate register should be set to
the first byte of the prefix, rather than the drive number field.

The Disk Transfer Area (DTA)
DOS 4.00 uses a buffer in memory, the Disk Transfer Area (DTA), to
hold the data for FCB file reads and writes. The DTA can be at any
location within the data area of your program and should be specified
by your program.
Only one DTA can be in effect at a time, so your program must tell
DOS 4.00 which memory location to use before issuing disk read or
write functions. When a program is given control by
COMMAND.COM, a default DTA large enough to hold 128 bytes is
established at 80H in the program segment prefix.

4·5

DOS 4.00 provides the following functions within interrupt 21H to
handle DTA activities:

Activity

Function
Number

Specifying the buffer address for reading and writing data
in the DTA

1AH

Requesting the buffer address for reading and writing data
in the DTA

2FH

Accessing Files
An FCB can identify a file on any valid drive, but only in the current
directory of the specified drive.
If SHARE has not been loaded, the number of files that can be open at
a time (using FCB function calls) is not restricted. When file sharing
is loaded, however, the maximum number of FCB opened files is
limited by the value specified in the FCBS command in CONFIG.SYS.
You can specify two values, m and n, using the FCBS command. The
m value specifies the total number of files that can be opened by
FCBS. The n value specifies the number of files opened by FCBs that
are protected from being closed.
When the maximum number of FCB opens is exceeded, DOS 4.00
automatically closes the least recently used file. Any attempt to
access such a file results in the interrupt 24H critical error message,
"FCB not available." If this situation occurs while a program is
running, the value specified for m in the FCBS command should be
increased.
Do not use the same FCB to open a second file without closing the
first open file. If more than one file is to be opened concurrently, use
separate FCBs. To avoid potential file sharing problems, close files
after I/O is performed. Close the file before trying to delete or
rename an open file.

4-6

Managing files using the FCBS command can be performed using the
following function calls:

Activity

Function
Number

Opening a file

OFH

Closing a file

10H

Deleting a file

13H

Creating a file

16H

Renaming a file

17H

Requesting the file size

23H

Separating the filename information into its components
(parsing)

29H

Accessing Sequential Records
By using the current block, current record, and record length fields of
the FCB, you can perform sequential 110 by using the following
sequential read or write function calls within interrupt 21H:

Activity

Function
Number

Reading from a record

14H

Writi ng to a record

15H

4·7

Accessing Random Records
Random 1/0 can be performed by filling in the random record and
record length fields in the FCB and issuing the following function calls
within interrupt 21H:

Activity

Function
Number

Reading from a single record

21H

Writing to a single record

22H

Specifying the random record field in the FCB

24H

Reading from multiple records

27H

Writing to multiple records

28H

Finding Files in Directories
Using the FCB as a source, finding and changing files in directories is
performed by the following functions within interrupt 21H:

Activity

Function
Number

Searching for the first matching file entry

11H

Searching for the next matching file entry

12H

Creating a file

16H

Deleting a file

13H

Renaming a file

17H

Separating the filename information into its components
(parsing)

29H

4-8

Chapter 5. Managing Device 1/0
This chapter provides guide and system architecture information
about the following tasks:
• Managing display 1/0
• Managing keyboard 1/0
• Managing miscellaneous 1/0
• Managing device redirection
• Accessing the system device drivers' control channel.

Managing Display 1/0
DOS 4.00 provides four functions within interrupt 21 H that send characters or stri ngs of characters to the screen.

Activity

Function
Number

Outputting a character to the screen, with the ability to
trigger the control-break interrupt handler

02H

Waiting until a character is input and outputting it to the
screen without the ability to trigger the control-break interrupt handler

06H

Outputting a string of characters in memory to the screen

09H

Outputting a string of characters in a buffer to the screen
or writing the string to a file device

40H

For further information on specifying character attributes, foreground
and background screen colors, and screen size using ANSI.SYS, see
the DOS 4.00 Command Reference.

5·1

Managing Keyboard 1/0
DOS 4.00 provides a full complement of functions within interrupt 21 H
that your application program can use to manage keyboard 110.

Activity

Function
Number

Sending input from the keyboard (with echo) to the display

01H

Receiving input directly from the keyboard, or sending
output di rectly to the display

06H

Receiving input directly from the keyboard without echo

07H

Receivi ng input from the keyboard without echo to the
display with the ability to trigger the control-break interrupt handler

08H

Reading characters from the keyboard to the buffer

OAH

Checking the keyboard buffer status

OBH

Clearing the keyboard buffer; specifying which function to
call after clearing the buffer

OCH

For further information on reassigning the keys, see the DOS 4.00
Command Reference.

Managing Miscellaneous 1/0
Three functions are available to manage miscellaneous 110.

Activity

Function
Number

Auxiliary Input

03H

Auxiliary output

04H

Printer output

05H

5-2

Managing File System Activities
The following system activities are supported by DOS 4.00:

Activity

Function
Number

Requesting the local computer ID

5EOOH

Specifyi ng the pri nter setup stri ng

5E02H

Requesting the printer setup string

5E03H

Requesting redirection list

5F02H

Attaching to a redirect device

5F03H

Canceling redirection

5F04H

Writi ng all data from a file to a device

68H

Accessing the System Device Drivers' Control
Channel
Function 44H within interrupt 21H is a mUlti-purpose function for
accessing the device drivers' control channel. Using function 44H,
your application program can request the status of a device and read
and write to the 1/0 control channel. The following subfunction values
should be passed in AL:
Subfunctlon
Number

Category

Activity

Reading and writing data to
a character device

Reading from a character
device

02H

Writing to a character
device

03H

Reading from a block device

04H

Writing to a block device

05H

Requesting the logical drive

OEH

Specifying the logical drive

OFH

Specifying how many times
(and intervals) DOS 4.00
should try to resolve shared
file conflicts

OSH

Controlling 110 for file
handles

OCH

Controlling 110 for block
devices

OOH

Determining whether a
logical device is local or
remote

09H

Determining whether a file
handle is local or remote

OAH

Reading and writing data to
a block device

Requesting and specifying
the logical drive

Providing network support
for devices

5-4

Reading and Writing Data in Binary and ASCII Modes
A program can use function 44H to change the mode in which data is
read or written to a device. If 110 is performed in binary mode,
control values have no meaning. If 110 is performed in ASCII mode,
certain control values have meaning. They are shown in the following table:
Control
Value

Keyboard
Input

Meaning

1AH

End-Of-File

ODH

Carriage Return

OAH

Line Feed

03H

Control Break

13H

Scroll Lock

10H

Print Screen

11H

Scroll restart

04H

End of Task

When a file is read in ASCII mode, it is echoed to the display and tabs
are expanded into spaces. They are left as a tab byte (09H) in the
input buffer. When a file is written in ASCII mode, tabs are expanded
to 8-character boundaries and filled with spaces (20H).

5·5

5-6

Chapter 6. Controlling Processes
This chapter provides guide and system architecture information
about the following activities:
•
•
•
•
•
•
•
•
•

Identifying a program at load time
Loading and executing a subprogram
Terminating a program/subprogram
Loading an overlay without executing it
Calling a command processor
Responding to errors
Respondi ng to a control-break action
Requesting and specifying the system date and time
Requesting and specifying the interrupt vectors.

Allocating Memory
DOS 4.00 keeps track of allocated and available memory blocks and
provides three function calls for application programs to communicate their memory requests.

Activity

Function
Number

Allocating memory

48H

Freeing allocated memory

49H

Changing the size of blocks of allocated memory

4AH

DOS 4.00 Memory Management
DOS 4.00 manages memory by allocating 16-byte units called paragraphs and building a control block for each allocated block. Any
allocation is 16 bytes larger than the actual request because DOS
4.00 automatically allocates a control block to keep track of each allocated block.
When the user starts the program at the command line,
COMMAND.COM loads the executable program module into the
largest unused block of available memory and reads the file header.
6-1

If there is not enough memory available, the system returns an error
code and passes control to the program. Your program should use
the SETBLOCK function call (4AH) to reduce allocated memory to the
size it needs.
Note: Because it is likely that the default stack supplied by DOS 4.00
lies in the area of memory being freed, a .COM program
should remember to set up its own stack before issuing a
SETBLOCK. The SETBLOCK call frees unneeded memory
which then can be used for loading subsequent programs.
If your program requires additional memory during processing, issue
function call 48H within interrupt 21. To free memory, issue function
call 49H within interrupt 21.

The DOS 4.00 Memory Map
The following table illustrates the order in which the DOS 4.00 components and application programs are located in memory:
Location

Use

0000:0000

Interrupt vector table

0040:0000

ROM communication area

0050:0000

DOS 4.00 communication area

XXXX:OOOO

IBMBIO.COM - DOS 4.00 interface to ROM I/O
routines

XXXX:OOOO

IBMDOS.COM - DOS 4.00 interrupt handlers,
service routines (INT 21 functions)

XXXX:OOOO

DOS 4.00 buffers, control areas, and installed
device drivers

XXXX:OOOO

Resident portion of COMMAND.COM - Interrupt
handlers for interrupts 22H (terminate), 23H (CtrlBreak), 24H (critical error), and code to reload
the transient portion

&·2

Location

Use

XXXX:OOOO

External command or utility - .COM or .EXE file

XXXX:OOOO

User stack for .COM files

XXXX:OOOO

Transient portion of COMMAND.COM

Memory map addresses are in segment:offset format. For example,
0070:0000 is absolute address 00700H.
The DOS 4.00 Communication Area is used as follows:
0050:0000 Print screen status flag store

Print screen not active or successful print screen
operation

Print screen in progress

255

Error encountered during print screen operation

0050:0001 Used by BASICA
0050:0004 Single-drive mode status byte

Diskette for drive A was last used

Diskette for drive B was last used

0050:0010-0021

Used by BASICA

0050:0022-o02F

Used by DOS 4.00 for diskette initialization

0050:0030-0033

Used by MODE command.

All other locations within the 256 bytes beginning at 0050:0000 are
reserved fur DOS 4.00 use.

6-3

Identifying a Program at Load Time
DOS 4.00 provi~es two function calls for application programs to
specify and identify themselves at load time:

Activity

Function
Number

Creating the means for DOS 4.00 to identify a program at
load time through the program segment prefix (PSP)

26H

Requesting how DOS 4.00 identified a program at load
time

62H

The Program Segment
When you enter an external command or call a program with the
EXEC function call (4BH), DOS 4.00 determines the lowest available
address in memory and assigns it to the program. That area of
memory is called the program segment. At offset 0 within the
program segment, DOS 4.00 builds a program segment prefix control
block. When an EXEC is issued, DOS 4.00 loads the program at offset
100H and gives it control. See Figure 6-1 on page 6-5 for an illustration of the program segment prefix.

8-4

INT
20H
8

Crtl-break
exit address
CS
18

Terminate
address
CS

Critical error
exit address
IP

Environment
pointer

Reserved

Ctrl-break
exit address
IP
16

Reserved

CS
2B

Reserved

Terminate
address
IP

Reserved
10

Top of
memory

Reserved

Unopened Standard
FCB1

Reserved
60

Reserved

OOScali

Unopened Standard FCB1 (cont)

Unopened Standard FCB2

FCB1 (cont)
70

Unopened Standard FCB2(cont)
78

Unopened Standard FCB2 (cont)

Parm
length
F8

,..

Figure

Command parameters
starting with leading blanks
F9

~~
FE

Command parameters

6-1. The Program Segment Prefix

8-5

The program segment prefix's first segment of available memory is in
paragraph form; that is, 1000H represents 64KB. The word at offset 6
contains the number of bytes available in the segment.
Offset 2CH contains the environment's paragraph address.
Offset SOH contains code to invoke the DOS 4.00 function dispatcher.
By placing the desired function number in AH, a program can issue a
long call to PSP + SOH to invoke a DOS 4.00 function rather than
issuing an interrupt 21 H.
The default disk transfer address is set to 80H.
An unformatted parameter area at 81 H contains all the characters
entered after the command name, including leading and imbedded
delimiters, with 80H set to the number of characters. If the <, >, or I
parameters were entered on the command line, they and the
filenames associated with them will not appear in this area because
redirection of standard input and output is transparent to applications.
For .COM files, offset 6 (one word) contains the number of bytes available in the segment.
Register AX contains the drive specifiers entered with the first two
parameters as follows:
AL= FFH if the first parameter contained an invalid drive specifier
(otherwise AL=OOH).
AH = FFH if the second parameter contained an invalid drive
specifier (otherwise AH = OOH).
In .EXE programs DS and ES registers are set to point to the program
segment and CS, IP, SS, and SP registers are set to the values
passed by the Linker.
In .COM programs all four segment registers contain the segment
address of the initial allocation block, starting with the program
segment prefix control block. The instruction pOinter (IP) is set to
100H. The SP register is set to the end of the program's segment.
The segment size at offset 6 is rounded down to the paragraph size.

6-6

Loading and Executing Overlays
Your program can use the 4BH function call to load optional overlays.
Function 4BH, value 0, loads and executes a program with overlays.
Function 4BH, value 3, loads an overlay without executing it.
If your program calls an overlay, the EXEC call assumes the calling
program has already allocated memory for the overlay. The request
to load an overlay does not verify that the calling program owns the
memory into which the overlay is to be loaded. An overlay loaded
into memory not allocated to it can damage the DOS 4.00 memory
management control blocks. This will not be evident until DOS 4.00
needs to use its series of control blocks.
If a memory allocation error is returned, the problem must be corrected and the system restarted. Overlays should not issue
SETBLOCK calls because they do not own the memory in which they
operate. The memory is controlled by the calling program.

The Parameter Block
When your program calls a subprogram using the EXEC call (4BH), it
can pass a parameter block which provides the subprogram with the
following:
• The environment string
• A command line which permits it to act like another command
processor
• File control blocks at 5C and 6C in the program segment prefix
(optional).
The Environment String
The environment passed from the calling program is a copy of its
environment. The segment address of the passed environment is
contained at offset 2CH in the program segment prefix.
The environment is a series of ASCII strings totaling less than 32KB
in the form:
NAME = parameter

Note: NAME= is always in uppercase.
8-7

Each string is terminated by a byte of O's. The complete series of
strings is terminated by another byte of O's. Another ASCII string
containing the word count and an ASCIIZ string containing the executable program's drive, path, filename, and extension follow the series
of environment strings.
The environment built by the command processor and passed to all
called programs contains a COMSPEC= string, the last PATH,
APPEND and PROMPT commands issued, and any environment
strings specified with the SET command.
The Command Line
Your program must create a command line which will be transferred
to the subprogram.
The File Control Blocks
If your program is using files based on file handles, the file control
blocks are of no concern. If your program is using file control blocks,
and either 5CH or 6CH contain a pathname, the corresponding FCB
will contain only a valid drive number. The filename field will not be
valid.

Terminating a Program/Subprogram
DOS 4.00 provides four functions and two interrupts to terminate programs. It also provides an interrupt to permit your program to specify
where control is to be passed upon termination.

Activity

Function
Number

Terminating a program and passing control to the calling
process

4CH

Terminating a program with a specified portion remaining
in memory

31 H

6-8

Activity

Function
Number

Terminating a program

OOH

Determining how a process ended

4DH

Interrupt 20H terminates a program. Interrupt 27H terminates a
program with a specified portion remaining in memory. Interrupt 22H
specifies where control is to be passed upon program termination.
When a subprogram terminates, control is returned to the calling
program. Before terminating, the calling program must return to the
system the memory it allocated to the subprogram. When the calling
program terminates, control is returned to DOS 4.00. DOS 4.00 does
a CHECKSUM to determine if the transient portion of
COMMAND.COM has been modified. If it has, DOS 4.00 reloads
COMMAND.COM based on the path specified in the environment.
The program returns from executing in ohe of the following methods:
•
•
•
•

By a jump to offset 0 in the program segment prefix
By issuing an INT 20H
By issuing an INT 21H with register AH=OOH or 4CH
By calling location 50H in the program segment prefix with
AH=OOH or 4CH.
Using INT 21 H is the preferred method.
All programs must ensure that the CS register contains the
segment address of the program segment prefix when terminating using any of the preceding methods except call 4CH.
All of the preceding methods return control to the program that
issued the EXEC. During the process, interrupt vectors 22H, 23H,
and 24H (terminate, Ctrl-Break, and critical error exit addresses)
are restored from the values saved in the program segment
prefix of the terminating program. Control is then given to the
terminating address.

6·9

Loading an Overlay without Executing It
If AL=3 is specified within function call 4BH, no program segment
prefix is built, and DOS 4.00 assumes the calling program has allocated memory for the overlay. The calling program should provide
memory in one of two ways:
• Provide enough memory for the overlay when it issues the
SETBLOCK call (4AH)
• Free adequate memory with the 49H call.
When DOS 4.00 receives an AL = 3 request, the system assumes that
the requested memory is owned by the calling program. As in subprograms, an overlay can be loaded into memory not allocated to it
and damage the series of DOS 4.00 memory management control
blocks.
Programs loaded with AL = 3 should not issue the SETBLOCK call
(4AH) because the memory in which they operate is owned by the
calling process, not the overlay. Before terminating, the calling
program must return to the system the memory it allocated to the
overlay. When the calling program terminates, control is returned to
DOS 4.00.

Calling a Command Processor
To call a command processor, you must do the following:
• Assure that adequate free memory is available to contain the
second copy of the command processor and the command it is to
execute. Issue function call 4AH to shrink allocated memory to
your current requi rement. Issue function call 48H with
BX = FFFFH. The return is available memory.
• Build a parameter string for the secondary command processor
in the form:
1 byte = length of parameter string
xx byte = parameter string
1 byte = OOH (carriage return)

6-10

For example, the following assembly statement builds the string
to execute a DISKCOPY command:
DB 19. "/C C:DISKCOPY A: B:" • 13

• Use the EXEC function call (4BH, function value 0) to execute the
secondary copy of the command processor. The COMSPEC =
parameter in the environment passed at PSP+2CH identifies the
drive, directory, and command processor name. Remember to
set offset 2 in the EXEC control block to point to the parameter
string.

Responding to Errors
When a DOS 4.00 function cannot be performed (indicating a critical
error situation) control is transferred to interrupt 24H. Function 59H
provides additional information on the error condition.
Activity

Number

Responding to a critical error situation

Interrupt
24H

Requesting additional error information and suggested
action

Function
59H

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.
The Extended Error function call (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.

6-11

Responding to a Control-Break Action
Interrupt 23H is issued if a Ctrl-Break occurs during standard 110.
Function calls 09H and OAH can be used if there is a AC, carriage
return and line feed produced as output.
Activity

Function
Number

Responding to a control-break action

23H

Displaying string

09H

Buffering keyboard input

OAH

If a Ctrl-Break is entered during standard input, standard output,
standard printer, or asynchronous communications adapter operations, an INT 23H is executed. If BREAK is on, INT 23H is checked
on most function calls, except 06H and 07H.
The user-written Ctrl-Break routine can use function calls 09H, OAH,
and ODH to respond to the Ctrl-Break action by having "C, carriage
return, and line feed produced as output. ASCII codes ODH and OAH
represent carriage return and line feed, respectively. If the CtrlBreak routine saves all registers, it may end with an IRET (return
from interrupt) instruction to continue program execution. If the
routine returns with a long return, the carry flag is used to determine
whether or not to stop execution. If the carry flag is not set, execution
continues, as with an IRET.
There are no restrictions on what the Ctrl-Break handler is allowed to
do, providing the registers are unchanged if IRET is used.

6-12

Requesting and Specifying the System Date and
Time
The following functions get or set the system date and time:

Activity

Function
Number

Requesti ng the system date

2AH

Specifyi ng the system date

2BH

Requesting the system time

2CH

Specifying the system time

2DH

Requesting and Specifying the Interrupt Vectors
A program can create and change the contents of the interrupt
vectors, the 4-byte addresses of the routines in memory that service
hardware and software interrupts. On exit, the program must reset
the interrupt vectors to where they were pointing originally.
If you want a program to examine or specify the contents of an interrupt vector, use DOS 4.00 function calls 35H and 25H and avoid referencing the interrupt vector locations directly.

Activity

Function
Number

Requesting the interrupt vector value

35H

Specifying the interrupt vector value

25H

6-13

6-14

Part 2. Using the Programming Utilities

Chapter 7. Creating Object Code Libraries
This chapter describes how to use the IBM Library Manager/2,
L1B.EXE on your utilities diskette, to create and maintain object code
libraries.

The IBM Library Manager/2
The IBM Library Manager/2 allows you to store object files in library
modules so they can be referred to by your application program
object fi les.
You can provide input to the IBM Library Manager/2 (LIB) by:
• Responding to a series of prompts
• Entering input at the command line
• Using a response file you have created.
We recommend that you allow LIB to prompt you for responses until
you are comfortable with its parameters and operations.
By entering information at prompts supplied by LIB, you can:
• Create a new library from one or more object files.
• Modify an existing library by:
Adding a module
Erasing a module
Replacing a module
Copying a module to an object file
Removing a module to an object file.
• Combine libraries.
• Create a library cross-reference listing.
• Perform a library consistency check.
• Set the library page size.
The prompts and the allowable responses are described below. See
"Creating and Maintaining Libraries" on page 7-9 for a description of
library management tasks.

7-1

Starting the LIB.EXE Utility
To start LIB, type
LIB

at the command line and press the Enter key. LIB prompts you for
information by displaying the following prompts, one at a time:
Library name:
Operations:
List file:
Output library:

Each time LIB displays a prompt, it waits for your response before it
displays the next one. With the exception of the first prompt, you can
respond by just pressing the Enter key. LIB supplies the default
response and takes you to the next prompt. At any prompt you can
select the defaults for all the remaining prompts by typing a semicolon (;) and pressing the Enter key.
An error message will cause the LIB session ~o end. For a list of LIB
error messages, see "Library Manager Error Messages" on
page 7-15. You can cause the library manager session to end at any
time by pressing Ctrl+Break. Control is then returned to DOS 4.00.
The responses to LIB prompts are described below.
Library Name Prompt

After you have entered LIB to start the library manager, the following
prompt is displayed:
Library Name:
Here is where you tell LIB the name of library you want it to manage.
You can type the filename of an existing library, or you can type a
new filename for a library you want to create. You must enter the
name of a library; there is no default response.
If you do not include an extension with your filename, LIB automatically supplies a .LlB extension.
If the library is an existing one that does not have a .LlB extension,
you must type its extension; otherwise LIB will not be able to find the

7-2

library. If the existing library is in a directory other than your current
one or on another drive, you must include this information.
Perform a consistency check: At this prompt you can have LIB
perform a consistency check on an existing library by typing a semicolon (;) immediately after the library name and pressing Enter. This
procedure is usually not necessary for libraries created with LIB.
If you are creating a library, type a new file specification. You can
include a drive and path. LIB will respond by displaying this prompt:
Library file does not exist. Create?

To confirm you want to create a library, type Y. Typing N ends the
LIB session and returns you to the DOS prompt.
Set the page size: At this prompt you can specify a page size for the
library. Type the page size option IP:n, where n is the number of
bytes in a page. If you do not specify a page size, the default is 16
bytes for a new library and the current page size if the library already
exists. See "Setting the Library Page Size" on page 7-13 for more
information.
Operations Prompt
LIB displays the next prompt:
Operations:

At this prompt you can type anyone of the command symbols
described below, immediately followed by the name of an object file,
a library, or a library module, depending on the operation you are
performing. When you use the name of a module, remember that a
module name has no path and no extension.
You can include as many operations (a symbol followed by the name
being operated on) as will fit on the line.
When you are manipulating a large number of modules or files, you
can type more than one line of information by typing an ampersand
(&) as the last character on the line and pressing Enter. LIB will then
repeat the Operations prompt, allowing you to enter more information. The ampersand must follow a filename and not a command
symbol.

7-3

The following table lists the symbols used at the Operations prompt:
Symbol and Task Description

Example

Add an object file to a library: Type a plus sign
followed by an object filename to copy the contents of the file into a library module. If the
object file is not in your current directory,
specify a path. If you omit the .OBJ extension,
LIB looks for a file with an .OBJ extension.

+c:\obj1

Add a library: Type a plus sign followed by a
library filename to copy a library to the library
specified at the Library name prompt: You
must type the library file's extension. Otherwise LIB looks for a file with an .OBJ extension.

+mylib.lib

Erase a module: Type a minus sign followed by
a module name to erase the module from the
library. (Remember that a module name has
no path and no extension.)

-moda

-+ Replace a module: Type a minus sign, a plus
sign, and a module name to replace the
module with the contents of an object file of the
same name. LIB assumes the object file is in
your current directory and has an .OBJ extension.

-+modb

Copy a module: Type an asterisk (*) followed
by a module name to copy the module to an
object file of the same name. The module
remains in the library. LIB gives the new file
an .OBJ extension and places it in your current
working directory.

*modc

- *

Remove a module: Type a minus sign, asterisk,
and module name to remove the module from
the library and place it in an object file of the
same name. LIB places the new file in your
current directory and gives it an .OBJ extension.

-*moda

The default for the Operations prompt is no operations performed.
7-4

List File Prompt

This prompt is displayed:
List File:

Type a filename at this prompt if you want to create a cross-reference
listing for your library. You can include a drive and path. If you do
not include an extension, LIB does not supply a default extension.
If you do not type a filename, the default filename is NUL.LST, which
means cross-reference information will not be saved.
For a description of the contents of the cross-reference listing, see
"Creating a Cross-Reference Listing" on page 7-12.
Output Library Prompt

This prompt is displayed:
Output library:

Next to the prompt is the name of the library you specified at the
Library name prompt.
If you typed in the name of an existing library at the Library name
prompt, and you want to create a new library with the changes you
have made, type in a new name.
If you typed in the name of a new library at the Library name prompt,
and you want to change the name, type in a new name.
If you accept the default and press the Enter key, your library is given
the name you typed at the Library name prompt. If the library is an
existing one, the original library keeps the same name but is given an
extension of .BAK.

Entering Input at the Command Line
To supply input to LIB at the command line, enter the parameters in
the format that follows. You may include a drive and path specification for any of the filenames you enter.

7-5

LIB --library

-----c---------......,.."""T'-------r----..
\

•

IPAGESIZE: number

~ operations J

~.Ii.tfileJ ~.neWllbr.ryJ

library

This required parameter along with the optional
IPAGESIZEnumber parameter corresponds to the
Library name prompt. If you want LIB to perform a consistency check on the library, type a semicolon after the
library name.

IPAGESIZE

This parameter sets the library page size in bytes. The
minimum abbreviation you can type is IP:number. The
allowable values for number are 16, 32, 64, 128,256, or
32,768. For more information on the IPAGESIZE option,
see "Setting the Library Page Size" on page 7-13.

operations

This parameter corresponds to the Operations prompt.
If you are typing in a lot of operations and know that
your input will exceed a line boundary, type an ampersand (&) after the last complete operation on the line
and press the Enter key. LIB then displays the Operations prompt so you can continue typing.
See "Operations Prompt" on page 7-3 for descriptions
of the operations you can enter.

,lIstflle

This parameter corresponds to the List file prompt. It
tells LIB to create a cross-reference listing for your
library. If you specify a filename, you must type a
comma preceding the filename. See "Creating a CrossReference Listing" on page 7-12 for a description of this
file's contents.
If you do not want a list file created, specify an additional comma instead of a filename.

,newllbrary

7-6

This parameter corresponds to the Output Library
prompt. Specify a filename if you want a new name for
a revised library. You must type a comma preceding
the filename. If you do not want to specify a filename
here, specify an additional comma instead.

A semicolon tells LIB you have completed your input.
If you enter a partial command line without a semicolon, LIB displays
the prompts for the remaining parameters. You can enter a value as
each prompt appears or press the Enter key to accept the default. If
you type a semicolon after any parameter, LIB supplies the defaults
for the remaining parameters.

Examples of Command Line Input
To add the file TEST.OBJ to the library BASIC.LlB without producing a
cross-reference, type:
LIB BASIC.LIB+TEST.OBJ;
Note that the following has the same result as the preceding example:
LIB BASIC.LIB+TEST;

Extensions are optional, and they default to .OBJ if omitted. If you
are using a library file in an operations list, you must specify the .LlB
extension.
To erase TEST from BASIC.LlB, type:
LIB BASIC-TEST;

To replace TEST in the library with a newer version, type:
LIB BASIC-+TEST;

Note that the following also have the same effect:
LIB BASIC-TEST+TEST.OBJ;
LIB BASIC+TEST-TEST;

If you want to make the same change, except to put the changes in a
new library called BASNEW.LlB, any of the following will work:
LIB BASIC-+TEST •• BASNEW
LIB BASIC-TEST+TEST •• BASNEW
LIB BASIC+TEST-TEST •• BASNEW

If you want to create a library of object modules, type:
LIB MYSUBS+FILEl.OBJ+FILE2.0BJ+ ••• +FILEH.OBJ

You are asked for the listing file.
7·7

Using a Response File
To operate the library manager with a response file, you must first
create a file that contains the responses you want LIB to process.
You can give your file any name you want. The responses you put in
the file must be in the same order as the LIB prompts:
Library name
Operations
List file
Output library name

The library name and the list of operations can appear on one line. If
your operations extend over one line, end the line with an ampersand
(&) and continue on the next line.
You can omit responses in your file and instead provide these
responses with a partial command line or have LIB prompt you for
them.
Once you have completed typing the responses, end the file with
either a semicolon or a carriage return and line feed combination. If
you do not end your file, LIB will display the last line of the file and
wait for you to press the Enter key.
When you are ready to tell LIB to process the contents of your
response file, you must specify the file with a preceding at sign (@),
like this:
LIB @C:\ABC\MYFILE.RSP

This tells LIB the file specification is for a response file, and not a
response to a prompt. Remember to include a path with your file
specification when the file is not in the current directory.
When you use the LIB command with a response file, LIB displays
each prompt on your screen with the corresponding response from
your file.
You can have LIB process only a part of your response file by placing
a semicolon on any line in the response file. When LIB reads the
semicolon, it supplies defaults for the remaining responses and
ignores the rest of the response file.

7-8

You can place all of your responses to the prompts in a response file.
The library manager is instructed by the following example to read
the responses from the response file:
LI B @RESP. TXT

where RESP.TXT is the filename containing the responses.
Note: RESP.TXT was chosen as an example. Any valid DOS filename
can be used.

Creating and Maintaining Libraries
This section summarizes the library management tasks you can
perform with LIB.

Creating a Library File
To create a new library file, type the name of the library file you want
to create following the Library name prompt. LIB supplies the .LlB
extension.
If the name of the new library is the name of an existing file, LIB
assumes you want to modify the existing file. When you give the
name of a library file that does not currently exist, LIB displays the
following prompt:
Library file does not exist. Create?

7-9

Type y (yes) to create the file; or n (no) to end the library session.
Note: When you call LIB in such a way that no Operations prompt
appears, the message above does not appear. LIB assumes y
(create the new library) by default. For example,

LIB new.lib+objl;
where new.llb does not exist, it creates the file new.llb.
You can specify a page size for the library when you create it. The
default page size is 16 bytes. See "Setting the Library Page Size" on
page 7-13 for more information.
After you give the name of the new library file, you can insert object
modules in the library by using the add operation (+) following the
Operations prompt. You can also add the contents of another library.
See "Adding Library Modules" on page 7-11 and "Combining
Libraries" on page 7-12 for an explanation of these options.

Modifying a Library File
You can change an existing library file by giving the name of the
library file following the Library name prompt. The Operations
prompt performs all operations you specify on that library.
LIB lets you keep both the original library file and the changed
version. You can do this by giving the name of a new library file following the Output library prompt. The library filename changes to the
new library filename, while the original library file remains
unchanged.
If you do not give a filename following the Output library prompt, the
changed version of the library file replaces the original library file.
LIB saves the original, unchanged library file. The original library file
has the extension .BAK instead of .LlB. At the end of the session you
have two library files: the changed version with the .LlB extension
and the original, unchanged version with the .BAK extension.

7-10

Adding Library Modules
Use the plus sign following the Operations prompt to add an object
module to a library. Give the name of the object file, without the .OBJ
extension, that you want to add immediately after the plus sign.
LIB removes the drive designation and the extension from the object
file specification, leaving only the filename. This becomes the name
of the object module in the library. For example, if the object file
B:\CURSOR.OBJ is added to a library file, the name of the corresponding object module is CURSOR. LIB always adds object
modules to the end of a library file.
Deleting Library Modules
Use the minus sign following the Operations prompt to delete an
object module from a library. Give the name of the module you want
to delete immediately after the minus sign. A module name has no
pathname and no extension. It is only a word, such as CURSOR.
Replacing Library Modules
Use a minus sign followed by a plus sign to replace a module in the
library. After the replacement symbol (-+), give the name of the
module you want to replace. Module names have no pathnames and
no extensions.
To replace a module, LIB deletes the given module, and adds the
object file with the same name as the module. The object file has an
.OBJ extension and resides in the current working directory.
Extracting Library Modules
Use an asterisk (*) followed by a module name to copy a module from
the library file into an object file of the same name. The module also
remains in the library file. When LIB copies the module to an object
file, it adds the .OBJ extension, the drive designation, and the
pathname of the current working directory to the module name. This
forms a complete object filename. You cannot override the .OBJ
extension, drive designation, or pathname given to the object file.
You can later rename the file or copy it to another location.

7-11

Use the minus sign followed by an asterisk (-*) to move an object
module from the library file to an object file. This operation is equivalent to copying the module to an object file, then deleting the module
from the library.

Combining Libraries
You can add the contents of a library to another library by using the
plus sign with a library filename instead of an object filename. Following the Operations prompt, give the plus sign and the name of the
library you want to add to the one you are changing. When you use
this option, you must include the .LlB extension of the library
filename. Otherwise, LIB assumes that the file is an object file and
looks for the file with an .OBJ extension.
LIB adds the modules of the library to the end of the library you are
changing. The added library still exists as an independent library.
LIB copies the modules without deleting them.
After you add the contents of a library or libraries, you can save the
new, combined library under a new name by giving a new name following the Output library prompt. If you omit the Output library
response, LIB saves the combined library under the name of the original library you are changing.

Creating a Cross-Reference Listing
You can create a cross-reference listing by giving a name for the
listing file following the List file prompt. If you omit the response to
this prompt, LIB uses the special filename NUL.LST, which tells LIB
not to save the cross-reference information.
A cross-reference listing file contains two lists. The first is an alphabetic listing of all public symbols in the library. The name of the
module the symbol name refers to comes after that symbol name.
For example, the cross-reference for BASCOM20.LlB contains:
$SWPA ••.••.• SWAP
$SWpc ••••..• SWAP

$SWPB •.••..• SWAP
$SWPD •..•..• SWAP

In this case, the modul9 names are all the same.
The second list is an alphabetic list of the modules in the library.
Under each module name is an alphabetic listing of the public
7-12

symbols to which the module refers. The module name includes its
offset value, and its code and data size in hexadecimal. In this
example, the module's name is SWAP.
SWAP Offset: 21979H Code and data size: 4FH
$SWPA
$SWPB
$SWPC
$SWPD

Performing Consistency Checks
When you give only a library name followed by a semicolon at the
Library name prompt, LIB performs a consistency check, displaying
messages about any errors it finds. It does not make any changes to
the library. This option is not usually necessary because LIB checks
object files for consistency before adding them to the library.
To produce a cross-reference listing along with a consistency check,
use the command prompt method of calling LIB. Give the library
name followed by a comma, then give the name of the listing file. LIB
performs the consistency check and creates the cross-reference
listing.

Setting the Library Page Size
The page size of a library affects the alignment of modules stored in
the library. Modules in the library are aligned so that they always
start at a position that is a multiple of n bytes from the beginning of
the file. The value of n is the page size. The default page size is 16
for a new library or the current page size for an existing library.
Because of the indexing technique LIB uses, a library with a larger
page size can hold more modules than a library with a smaller page
size. However, for each module in the library, this indexing technique wastes an average of nl2 bytes of storage space (where n is the
page size). In most cases a small page size is advantageous. You
should use the smallest page size possible.
To set the library page size, add a page size option after the library
filename in response to the Library name prompt:
library-name IPAGESIZE:n

The value of n is the new page size. It must be a power of 2 and must
be between 16 and 32768.
7-13

Another consequence of this indexing technique is that the page size
determines the maximum possible size of the .LlB file. This limit is
65536 times number. For example, IP:16 means that the .LlB file must
be smaller than 1 megabyte (16 times 65536 bytes) in size.

7-14

Library Manager Error Messages
Error messages produced by the IBM Library Manager/2, LIB, have
one of the following formats:
•
•
•

filenamelLlB: fatal error U1xxx : messagetext
filenamelLlB: error U2xxx: messagetext
filenamelLlB: warning U4xxx: messagetext

The message begins with the input filename (filename), if one exists,
or with the name of the utility. LIB may display the following error
messages:
U1150 page size too small
The page size of an input library is too small, which indicates a
non-valid input .LlB file.
U1151
syntax error: Illegal file specification
You gave a command operator, such as a minus sign, without a
module name following it; or an illegal filename or no filename at
all.
U1152 syntax error: option name missing
You gave a forward slash (I) without a value following it.
U1153 syntax error: option value missing
You gave the IPAGESIZE option without a value following it.
U1154 option unknown
An unknown option is given. Currently, LIB recognizes the
IPAGESIZE option only.
U1155 syntax error: Illegal Input
The given command did not follow correct LIB syntax.
U1156 syntax error
The given command did not follow correct LIB syntax.
Ut157 comma or new line missing
A comma or carriage return is expected in the command line, but
did not appear. This may indicate an inappropriately placed
comma, as in the following line:
LIB math.llb,-mod1

+ mod2;

7-15

The line should have been entered as follows:
LIB math.llb -mod1

+ mod2;

U1158 terminator missing
Either the response to the Output library: prompt or the last line
of the response file used to start LIB did not end with a carriage
return.
U1161
cannot rename old library
LIB could not rename the old library to have a .BAK extension
because the .BAK version already existed with read-only protection. Change the protection of the old .BAK version.
U1162 cannot reopen library
The old library could not be reopened after it was renamed to
have a .BAK extension.
U1163 error writing to cross-reference file
The disk or root directory is full. Delete or move files to make
space.
U1170 too many symbols
More than 4609 symbols appeared in the library file.
U1171
Insufficient memory
LIB did not have enough memory to run. Remove any shells or
resident programs and try again, or add more memory.
U1172 no more virtual memory
You should note the conditions when the error occurs and contact
your authorized IBM dealer.
U1173
Internal failure
You should note the conditions when the error occurs and contact
your authorized IBM dealer.
U1174 mark: not allocated
You should note the conditions when the error occurs and contact
your authorized IBM dealer.
U1175 free : not allocated
You should note the conditions when the error occurs and contact
your authorized IBM dealer.
U1180 write to extract file failed
The disk or root directory is full. Delete or move files to make
space.

7-16

U1181
write to library file failed
The disk or root directory is full. Delete or move files to make
space.
U1182 filename: cannot create extract file
The disk or root directory is full, or the specified extract file
al ready exists with read-only protection. Make space on the disk
or change the protection of the extract file.
U1183 cannot open response file
The response file was not found.
U1184 unexpected end-of-flle on command Input
An end-of-file character is received prematurely in response to a
prompt.
U1185 cannot create new library
The disk or root directory is full, and the library file already exists
with read-only protection. Make space on the disk or change the
protection of the library file.
U1186 error writing to new library
The disk or root directory is full. Delete or move files to make
space.
U1187 cannot open VM.TMP
The disk or root directory is full. Delete or move files to make
space.
U1188 cannot write to VM
You should note the conditions when the error occurs and contact
your authorized IBM dealer.
U1189 cannot read from VM
You should note the conditions when the error occurs and contact
your authorized IBM dealer.
U1190 Interrupted by user
User typed control-break while LIB was executing.
U1200 name: Invalid library header
The input library file has an invalid format. Either it is not a
library file, or it has been corrupted.
U1203 name : Invalid object module near location
The module specified by name is not a valid object module.

7-17

U2152 filename: cannot create listing
The directory or disk is full, or the cross-reference listing file
already exists with read-only protection. Make space on the disk
or change the protection of the cross-reference listing file.
U2155 modulename : module not In library; Ignored
The specified module is not found in the input library.
U2157 filename: cannot access file
LIB is unable to open the specified file.
U2158 libraryname: Invalid library header; file Ignored
The input library has an incorrect format.
U2159 filename: Invalid format hexnumber; file Ignored
The signature byte or word, hexnumber, of an input file is not one
of the recognized types.
U4150 modulename : module redefinition Ignored
A module is specified to be added to a library, but a module with
the same name is already in the library. Or a module with the
same name is found more than once in the library.
U4151
symbol(modulename) : symbol redefinition Ignored
The specified symbol is defined in more than one module.
U4153 number: page size Invalid; Ignored
The value specified in the IPAGESIZE option is less than 16.
U4156 libraryname : output-library specification Ignored
An output library is specified in addition to a new library name.
For example, specifying:
LIB new.llb + one.obJ,new.lst,new.llb
new.llb does not exist and causes this error.

7-18

Chapter 8. Creating an Executable File
This chapter describes how to use the IBM Linker/2, which is
LlNK.EXE on your utilities diskette, to produce executable programs.

The IBM Linker/2
The IBM Linker/2 combines object files with referenced library subroutines to produce a file which can be relocated and executed. The
object files you supply to the linker for processing must be compiled
or assembled source files that are written in the programming languages supported by DOS 4.00.
You can provide input to LINK by:
• Responding to a series of prompts
• Entering input at the command line
• Using a response file you have created.
We recommend that you allow LINK to prompt you for responses until
you are comfortable with its parameters and operations.

Starting the LINK.EXE Program
To start the linker, type
LINK

at the command line and press Enter. The linker prompts you for
information by displaying the following prompts, one at a time:
Object modules [.OBJ]:
Run file [filename.EXE]:
List file [NUL.MAP]:
Libraries [.LIB]:
Definitions File [NUL.DEF]:

Each time the linker displays a prompt, it waits for your response
before it displays the next one. With the exception of the first prompt,
you can respond by pressing the Enter key. The linker supplies the
default response and takes you to the next prompt. At any prompt

8-1

you can select the defaults for all the remaining prompts by typing a
semicolon (;) and pressing the Enter key.
You can also type in one or more linker options at any of the prompts.
A linker option instructs the linker to perform a special function as it
processes your object files. For example, specifying the IEXEPACK
option tells LINK to compress the .EXE file being created so it will
load faster. For descriptions of the options provided by LINK and
guidelines for using them, see "Using linker Options" on page 8-11.
Any error message generated by a response to a prompt will cause
the linker session to end. For a list of LINK error messages, see
"linker Error Messages" on page 8-37. You can cause the linker
session to end at any time by simultaneously pressing the Ctrl and
Break key so Control is then returned to DOS 4.00.
Object Modules Prompt
After you enter LINK to start the linker, this prompt is displayed:
Object Modules [.OBJ]:

Here is where you enter the names of the object files to be used to
create your .EXE file. You must enter the name of at least one object
file. Separate each object filename from the next by a blank space or
a plus sign (+). If a plus sign is the last character on the line when
Enter is pressed, the Object Modules prompt reappears, allowing you
to add more filenames.
If you do not type an extension for a filename, LINK automatically
supplies the .OBJ extension.
Include a drive and path with your file specification if the object file is
not on the current drive or in the current directory. If LINK cannot
find an object file, it does not display an error message until you have
answered all the prompts.
When you have completed typing your input, press the Enter key.
Run File Prompt
The next prompt is displayed:
Run File [filename.EXE]:

8-2

Here is where you name the .EXE file that will be created. The
filename displayed in this prompt is the first one you typed next to the
Object Modules prompt. If you do not supply a new name and just
press the Enter key, this will be the name of your file. It will have an
extension of .EXE.
List File Prompt

The next prompt is displayed:
List File [NUL.MAP]:

The linker list file is sometimes called the linker map. It contains the
names, load addresses, and lengths of all segments in a program. It
also lists the names and load addresses of any groups in the
program, the program's starting address, and messages generated
by any errors the linker may have encountered. For more information
on map file contents, see "Reading the Map File" on page 8-31.
If you do not want a list file, do not type a filename. When you press
the Enter key, the file NUL.MAP is created, which means LINK will not
save mapping information.
If you enter a filename without an extension, LINK supplies .MAP.
By typing the IMAP option after your file specification, you tell LINK to
include a list of all public symbols and their addresses in the map
file. If you enter only IMAP without a filename, LINK creates a map
file that includes the public symbol information and has the same
name as the first object file you specified for the Object Modules
prompt. Its extension will be .MAP.
Libraries Prompt

The next prompt is displayed:
Libraries [.LIB]:

List the names of the libraries you want linked and the names of any
directories you want searched for library names whose paths have
not been specified. Separate these specifications with a blank space
or a plus sign (+).

8-3

When you supply directory specifications, LINK uses them to search
for default compiler libraries referred to in object files. If you do not
supply a filename extension for a library, LINK substitutes .LlB.
The linker uses the environment variable LIB to search for libraries.
Using the SET command, you can assign the names of directories as
well as complete file specifications to LIB as search paths. If you
have defined search paths to the linker with LIB, this determines what
information you need to enter. For example, if you have included the
search path to the directory that contains your library in the value you
set for LIB, you need enter only the library name, not its path, at the
prompt. If you have included the entire file specification in the LIB
definition, then this library will be searched when references to public
symbols are encountered. For a description of the SET command,
refer to the DOS 4.00 Command Reference.
The maximum number of search paths you can enter at this prompt is
limited to 32. If your input is going to exceed a line, make the last
character on the line a plus sign (+) and press the Enter key. LINK
then repeats the prompt so you can continue to type.
To locate the default libraries, LINK searches in the following order:
1. The current working directory
2. The directories in the order listed following the Libraries prompt
3. The libraries specified by the LIB environment variable.
LINK searches all the libraries until it finds the first definition of a
library public symbol.
If you do not require any libraries to be searched for object code,
press the Enter key.
Definition File Prompt
This is the prompt displayed by LINK:
Definition File [.DEF]:

Since this IBM Linker/2 parameter for creating a module definition
file is an IBM Operating System/2 parameter that is not supported by
DOS 4.00, press the Enter key in response to this prompt.

8-4

This completes your input to LINK, and LINK will now process the
information you have supplied. If no errors are encountered, LINK
creates your executable file.
LINK uses available memory for the link session. If the files to be
linked create an output file that exceeds available memory, LINK
creates a temporary disk file to serve as storage. LINK creates the
temporary file in the current working directory. If you are working in
a directory that is on a diskette, LINK displays the following message:

Temporary file name has been created.
Do not change diskette in drive letter:
The name is a unique temporary filename created by the linker. After
this message appears, do not remove the diskette from the given
drive (letter) until the link session ends. If you remove the diskette,
the operation of LINK is unpredictable. If LINK unexpectedly ends,
you may see the following message:

Unexpected end of fi 1e on name
If you get this message, you must restart link from the beginning.
After LINK creates the executable file, it automatically deletes the
temporary file.
An Example of a Prompts Session
The following example links the object modules MODA.OBJ,
MODB.OBJ, MODC.OBJ, and STARTUP.OBJ. LINK searches the
library file MATH.L1B in the \L1B directory on drive B for routines and
data used in the programs. LINK then creates an executable file
named MODA.EXE and a map file named ABC. MAP. The IPAUSE
option in the Object Modules prompt line causes LINK to pause while
you change diskettes. LINK then creates the executable file.
LINK

Object Modules [.OBJ]: moda + modb +
Object Modules [.OBJ]: modc + startup jPAUSE
Run File [MODA.EXE]:
List File [NUL.MAP]:abc
Libraries [.LIB]: b:\lib\math
Definitions File [NUL.DEF]:

8·5

Entering LINK Input at the Command Line
To run the linker from the command line, type the responses to LINK
prompts as parameters to the LINK command in the format that
follows.
LlNK-Objlist-~\----7-~""""\~---7--~\-----7--,.--a·

"- ,runfile J

"-- ,listfile .J

"-- ,librarylist J

,definitions-file
See option
list below

With the exception of linker options, which begin with a forward slash
(/) and can appear anywhere on the command line, parameters specified to LINK must be typed in the same order as the prompts are presented by LINK. Separate parameters by commas, and if you omit a
parameter within a sequence, specify an additional comma.
If you enter a partial command line that does not end in a semicolon,
LINK displays the prompts for the remaining parameters. You can
enter values for these prompts or just press the Enter key to accept
the defaults.
Refer to "Starting the LlNK.EXE Program" on page 8-1 for default
descri ptions.
obJllst

This parameter corresponds to the Object Flies
prompt. The linker requires at least one object file.
Separate file specifications by a blank space or a
plus sign (+). If your input will exceed one line, type
a plus sign as the last character on the line before
pressing Enter. The linker then displays the Object
Flies prompt.

,runflle

This parameter corresponds to the Run File prompt.
If specified, this is the name of the executable file
created by LINK.

,lIs8l1e

This parameter corresponds to the List File prom pt.
If specified, this is the name of the map file.

8-6

,lIbrarylist

This parameter corresponds to the Libraries prompt.
If specified, this is the list of libraries LINK searches
for object code routines.

,definitions file

This parameter for creating module definition files
corresponds to the Definitions File prompt. Module
definition files are not supported by DOS 4.00.

/optlonsllst

This parameter represents any linker options you
wish to specify. For the purpose of simplicity, the
command format shows this position for linker
options. Actually, you can put linker options anywhere on the command line. For a description of
linker options, see "Using Linker Options" on
page 8-11.
The semicolon tells LINK you have completed your
input. LINK supplies the defaults for any remaining
parameters.

Examples of Command Line Input
In the example below, an object module FILE.OBJ is processed to
create the executable file FILE.EXE. The linker searches the library
ROUTINE.L1B for routines and variables used within the program. It
also creates a file called FILE.MAP, which contains a list of the segments of the program and groups. The following examples creates
the file:
LINK file.obj,file.exe,file.map,routine.lib;

It is equal to the following line:
LINK file, ,file, routine;

In the following example, the linker loads and links the object
modules FUN.OBJ, TEXT.OBJ, TABLE.OBJ, and CARE.OBJ and
searches for unresolved references in the library file COBLlB.L1B. By
default, the executable file produced is named FUN.EXE. A list file
named FUNLlST.MAP is also produced.
LINK FUN+ TEXT + TABLE+CARE"FUNLIST ,COBLIB. LIB IMAP;

In the next example, LINK uses the two object modules
STARTUP .OBJ and FILE.OBJ on the current drive to create an executable file named FILE.EXE on drive B:. LINK also creates a map file in
8·7

the \MAP directory of the current drive but does not search any
libraries.
LINK startup-t-file,b:file,\map\file;

To link the application object file SAMPLE.OBJ using the the libraries
LlB1.LlB and LlB2.LlB, type:
LINK sample,sample.exe, sample.map/M/LI, libl+lib2/NOD;

This command creates the file SAMPLE.EXE. It also creates the map
file SAMPLE.MAP. The command searches the library files LlB1.LlB
and LlB2.LlB to resolve any external references made in
SAMPLE.OBJ. The INOD option directs LINK to ignore any default
libraries specified in the object file.
The linker uses default filename extensions if you do not explicitly
provide your own. In the example above, LINK extends the first
occurrence of the filename SAMPLE to SAMPLE.OBJ. LINK extends
the library files with the .LlB extension. The III option has LINK copy
the line number information from the object files.

Using a Response File to Supply LINK Input
To operate the linker with a response file, you must first create a file
that contains the responses you want LINK to process. You can give
your file any name you want. The responses you put in the file must
be in the same order as the LINK prompts:
objectfiles
[runfile)
[listfile)
[libraryfiles)
[defi nitionsfiIe]
Each response to a prompt must begin on a separate line, but you
can extend long responses across more than one line by typing a
plus sign as the last character of each incomplete line. You can place
one or more options on any line.

8-8

You can omit responses in your file and instead provide these
responses with a partial command line or have LINK prompt you for
them.
Once you have completed typing the responses, end the file with
either a semicolon or a carriage return and line feed combination. If
you do not end your file, LINK will display the last line of the file and
wait for you to press the Enter key.
When you are ready to tell LINK to process the contents of your
response file, you must specify the file with a preceding at sign (@),
like this:
LINK @C:\ABC\MYFILE.RSP

This tells LINK the file specification is for a response file, and not a
response to a prompt. Remember to include a path with your file
specification when the file is not in the current directory.
When you use the LINK command with a response file, LINK displays
each prompt on your screen with the corresponding response from
your file. If the response file does not contain responses for all the
prompts, LINK displays the appropriate prompts and waits for you to
enter responses. When you type an acceptable response, LINK continues the session.
You can have LINK process only a part of your response file by
placing a semicolon on any line in the response file. When LINK
reads the semicolon, it supplies defaults for the remaining responses
and ignores the rest of the response file. For example, if you type a
semicolon on the line of the response file corresponding to the Run
File prompt, LINK uses the defaults for the rest of the responses,
starting with the executable file response.
Examples of Response Flies
Suppose you enter these lines in a response file:
FUN TEXT TABLE CARE
/PAUSE /MAP
FUNLIST
COBLIB. LIB;
When the response file is processed, LINK loads the four object files
named FUN, TEXT, TABLE, and CARE. LINK produces two output
files named FUN.EXE and FUNLlST.MAP. The /PAUSE option causes

8·9

LINK to pause before producing the executable file (FUN.EXE). This
permits you to change diskettes if necessary. See the IPAUSE and
IMAP options under "Using Linker Options" on page 8-11 for more
information.

The response file below tells the linker to link the four object modules
MODA, MODB, MODC, and STARTUP. The linker pauses for you to
change diskettes before producing the runfile MODA.EXE. The linker
also creates a map file ABC. MAP and searches the library MATH.LlB
in the \LlB directory of drive B:.
moda modb mode startup /PAUSE
abc
b:\lib\math

The following example shows you how you can combine all three
methods of supplying file names. Assume that you have a response
file called LIBRARY that contains the following line:
libl+lib2+lib3+lib4;

Now start LINK with a partial command line:
LINK objectl object2

LINK takes OBJECT1.0BJ and OBJECT2.0BJ as its object files, and
asks for the next line with the following:
Run File [objectl.EXE]: exec
List File [NUL.MAP]:
Libraries [.LIB]: @library

Type exec so that the linker names the run file EXEC.EXE. Press the
Enter key to show that you do not want a map file, and type @ library
for the linker to use in the response file containing the four library
filenames.

8-10

Using Linker Options
The table below lists LINK options and describes what they do.
You can type linker options at any prompt or at any point on the
command line. You can specify an option's minimum abbreviation as
shown in the Options column, or as many characters of its long form
as you like. The long forms appear in parentheses. Remember to
include the leading forward slash (I) for each option you specify.
A complete format description, usage guidelines, and examples for
each option follow this table.
Option

Task Description

ICO

Prepare the .EXE file for later symbolic debugging
(lCODEVIEW). You should not use this option with
the IEXEPACK option.

ICP

Reduce the maximum amount of paragraphs
reserved for your program from the default of 64KB
minus 1 to whatever you specify
(lCPARMAXALLOC).

100

Force the ordering of segments (lDOSSEG).

IDS

Load data starting at the high end of the segment
(lDSALLOCATE). This option is used with the IHIGH
option.

Compress the .EXE file for faster loading
(/EXEPACK). You should not use this option with
the ICODEVIEW option.

IHE

Display a list of the LINK options on your screen
(lHELP).

IHI

Cause the .EXE file to be placed in the highest
storage available when loaded (lHIGH). This option
is used with the IDSALLOCATE option.

8·11

Option

Task Description

Display LINK processing messages (/INFORMATION).

III

Add a list of the starting addresses of program
source lines to your map file (/LINENUMBERS). If
you do not specify a map file, this option causes one
to be created.

Add a list of public symbols declared by your object
files to your map file (/MAP). If you do not specify a
map file, this option causes one to be created.

INOD

Ignore any default compiler library names found in
an object file (/NODEFAULTLIBRARYSEARCH).
This allows you to supply your own library names.

INOG

Provide compatibility with previous compiler versions (/NOGROUPASSOCIATION).

NOI

Distinguish between uppercase and lowercase characters (lNOIGNORECASE). This option is for files
created by compilers that make this distinction.

Set the interrupt number to other than 3FH for
passing control to overlays (lOVERLAYINTERRUPT).

IPAU

Pause before generating the .EXE file (lPAUSE).
This option allows you to insert a diskette.

ISE

Set the maximum number of logical segments to a
value other than the the default of 128 (/SEGMENT).

1ST

Set the stack size to other than the size calculated
by LINK (lSTACK).

8·12

Preparing Files for CodeView
ICODEVIEW

This option directs LINK to include symbolic debugging information
for CodeView in the output .EXE file for IBM languages that support
the CodeView debugger.

Format
ICODEVIEW
The minimum abbreviation is ICO.

Comments
Warning: If ICODEVIEW is used with the IEXEPACK option, all symbolic debugging information will be lost.

8·13

Reserving Paragraph Space
ICPARMAXALLOC

This option allows you to change the default value of the MAXALLOC
field, which controls the maximum number of paragraphs reserved in
storage for your program. A paragraph is defined as the smallest
storage unit (16 bytes) addressable by a segment register.

Format
ICPARMAXALLOC:number

The minimum abbreviation is ICP.

Comments
The maximum number of paragraphs reserved for a program is determined by the value of the MAXALLOC field at offset OCH in the EXE
header.
The default for the MAXALLOC field is 65535 (decimal), or 64KB
minus 1. You can reset the default to any number between 1 and
65535 (deCimal, octal, or hexadecimal). Reducing the number is
helpful because:
• Program efficiency is not increased by reserving all available
memory.
• You may need to run another program within your program and
you need to reserve space for the run program.
If the value you specify is less than the computed value of MINALLOC
(at offset OAH), the linker uses the value of MINALLOC instead.

8-14

Ordering Segments
IDOSSEG

This option forces segments to be ordered according to the following
rules:
1. All segments with a class name ending in CODE
2. All other segments outside of DGROUP
3. DGROUP segments in the following order:
a. Any segments of class BEG DATA. (This class name is
reserved for IBM use.)
b. Any segments not of class BEGDATA, ess, or STACK.
c. Segments of class ess.
d. Segments of class STACK.

Format
IDOSSEG
The minimum abbreviation is IDO.

8-15

Controlling Data Loading
IDSALLOCATE

By default, LINK loads all data starting at the low end of the data
segment. At run time, LINK sets the OS (data segment) pointer to the
lowest possible address to allow the entire data segment to be used.
You can use the IDSALLOCATE option to tell LINK to load all data
starting at the high end of the data segment. To do this, at run time,
set the OS pOinter to the lowest data segment address that contains
program data.

Format
IDSALLOCATE
The minimum abbreviation is IDS.

Comments
This option is typically used with the tHIGH option to take advantage
of unused storage within the data segment. You can reserve any
available storage below the area specifically reserved for OGROUP,
using the same DS pointer.

8-16

Packing Executable Files
IEXEPACK

This option directs LINK to remove sequences of repeated bytes (typically nulls) and to optimize the load-time relocation table before creating the DOS 4.00 executable file.

Format
IEXEPACK
The minimum abbreviation is IE.

Comments
Executable files linked with this option are usually smaller and load
faster than files linked without this option. However, you cannot use
symbolic debugging programs with packed files.
This option does not always save a significant amount of disk space
and sometimes actually may increase file size. Programs that have a
large number of load-time relocations (about 500 or more) or long
streams of repeated characters are usually shorter if packed.
Warning: If the ICODEVIEW option is used with IEXEPACK, all symbolic debugging information will be lost.

Example
This example creates a packed version of file PROGRAM.EXE.
LINK program IE;

8-17

Viewing the Options List

IHELP

This option causes LINK to write a list of the available options to the
screen. This may be convenient if you need a reminder of the available options. Do not give a filename when using the IHELP option.

Format
IHELP
The minimum abbreviation is IHE.

Example
LINK /HELP

Note: Many LINK options that are used only with IBM Operating
System/2™1 are displayed when using the /HELP option.
These options cannot be used when creating programs to run
on DOS 4.00.

Operating System/2 is a trademark of the International Business
Machines Corporation.

8-18

Controlling Run File Loading

IHIGH

You can place the run file as low or as high in storage as possible.
Using the IHIGH option directs LINK to cause the loader to place the
run file as high as possible in storage without overlaying the transient
portion of COMMAND.COM. The COMMAND.COM file occupies the
highest area of storage when loaded. Without the IHIGH option, the
loader places the run file as low as possible in storage.
Use the IHIGH option in association with the IDSALLOCATE option.

Format
IHIGH
The minimum abbreviation is IHI.

8-19

Displaying LINK-Time Information
IINFORMATION

This option causes the linker to display the phase of processing it is
running, and the name of each input module as it is linked. This is
useful during debugging.

Format
IINFORMATION
The minimum abbreviation is II.

8-20

Copying Line Numbers to the Map File
ILINENUMBERS

This option directs the linker to copy the starting address of each
program source line to a map file. The starting address is the
address of the first instruction that corresponds to the source line.

Format
ILiNENUMBERS
The minimum abbreviation is Ill.

Comments
LINK copies the line number data only if you give a map filename in
the LINK command line, and only if the given object file has line
number information. Line numbering is available in some high-level
languages.
If an object file has no line number information, the linker ignores the
/LiNENUMBERS option.
Note: If you do not specify a map file in a LINK command, you can
still use the ILiNENUMBERS option to force the linker to create
a map file. Place the option at or before the List File prompt.
LINK gives the forced map file the same filename as the first
object file specified in the .command and gives it the default
extension .MAP.

Example
This example causes the line number information in the object file
FILE.OBJ to be copied to the map file FILE.MAP.
LINK file/LINENUMBERS •• file.mylib;

8-21

Producing a Public Symbol Map

IMAP

This option causes LINK to produce a listing of all public symbols
declared in your program. This list is copied to the map file created
by the linker.

Format
IMAP:number

The minimum abbreviation is 1M.
For a complete description of the listing file format, see "Reading the
Map File" on page 8-31.

Comments
The number parameter specifies the maximum number of public
symbols that the linker can sort in the map file. The limit is 32768,
and the default is 2048 if no number is specified. If the limit is
exceeded, the linker produces an un-sorted list and issues the following warning:
MAP symbol limit too high
If you get this error, link again with a lower number. The limit varies
according to how many segments the program has and how much
memory is available.
Specifying a number also causes the public symbols to be sorted by
address only, not by name, regardless of the number. To reduce the
size of your map files by removing the list sorted by name, link with
IMAP followed by the lowest possible number that will accommodate
the number of public symbols in your program.
Note: If you do not specify a map file in a LINK command, you can
use the IMAP option to force the linker to create a map file.
LINK gives the forced map file the same name as the first
object file specified in the command and the default extension
.MAP.
8-22

Ignoring Default Libraries
INODEFAULTLIBRARYSEARCH

This option directs the linker to ignore any library names it may find
in an object file. A high-level language compiler may add a library
name to an object file to ensure that a default set of libraries is linked
with the program. Using this option bypasses these default libraries
and lets you name the libraries you want by including them on the
LINK command line.

Format
INODEFAULTLiBRARYSEARCH
The minimum abbreviation is INOD.

Example
This example links the object files STARTUP.OBJ and FILE.OBJ with
routines from the libraries EM, SLlBFP, and SLlBC. Any default
libraries that may have been named in STARTUP.OBJ or FILE.OBJ
are ignored.
LINK startup+file/NOD ••• em+slibfp+slibc;

8-23

Preserving Compatibility
INOGROUPASSOCIATION

This option causes the linker to process a certain class of fix-up routines in a manner compatible with previous versions of the linker.
This option is provided primarily for compatibility with previous versions of other IBM language compilers.

Format
INOGROUPASSOCIATION

The minimum abbreviation is INOG.

8-24

Preserving Lowercase
INOIGNORECASE

This option directs LINK to treat uppercase and lowercase letters in
symbol names as distinct letters. Normally, LINK considers uppercase and lowercase letters to be identical, treating the names TWO,
Two, and two as the same. When you use the INOIGNORECASE
option, the linker treats TWO, Two, and two as different names.

Format
INOIGNORECASE

The minimum abbreviation is INOI.

Comments
This option is typically used with object files created by high-level
language compilers. Some compilers treat uppercase and lowercase
letters as distinct letters and assume that the linker does the same.

Example
This command causes the linker to treat uppercase and lowercase
letters in symbol names as distinct letters. The object file FILE.OBJ
is linked with routines from the library \SLlBC.LlB located in the \LlB
directory.
LINK file/NOI ••• \lib\slibc;

8-25

Setting the Overlay Interrupt

IOVERLAYINTERRUPT

By default, the DOS 4.00 interrupt number used for passing control to
overlays is 3FH. This option allows you to select a different interrupt
number.

Format
10VERLAYINTERRUPT:number
The minimum abbreviation is 10.

Comments
The number can be a decimal number from 0 through 255, an octal
number from 0 through 0377, or a hexadecimal number from 0 to FFH.
Numbers that conflict with DOS 4.00 interrupts are not prohibited, but
IBM does not recommend their use.

8-26

Pausing to Change Disks
IPAUSE

This option causes LINK to pause so that you can change disks before
writing the executable file to disk.

Format
IPAUSE
The minimum abbreviation is IPAU.

Comments
If you choose the IPAUSE option, the linker displays the following
message before creating the run file:
About to generate .EXE file
Change diskette In drive letter and press
The letter is the proper drive name. This message appears after the
linker has read data from the object and library files, and after writing
data to the map file, if one was specified. LINK resumes processing
when you press the Enter key. After LINK writes the executable file
to disk, the following message appears:
Please replace original diskette
In drive letter and press
Note: Do not remove the disk used for the temporary file, if one has
been created. If the temporary disk message appears when
you have specified the IPAUSE option, you should simultaneously press the Ctrl and C keys to end the LINK session. Rearrange your files so that LINK can write the temporary file and
the executable file to the same disk, then try again.

8-27

Pausing to Change Disks

IPAUSE
Example
This command causes the linker to pause just before creating the
executable file file.exe. After creating the executable file, LINK
pauses again to let you replace the original disk.
LINK file/PAUSE.file •• \lib\math;

8-28

SeHing the Maximum Number of Segments
ISEGMENTS

This option directs the linker to process no more than number + 3
logical segments per program. If it meets more than this limit, the
linker displays an error message and stops linking. The /SEGMENTS
option bypasses the default limit of 128 logical segments.

Format
ISEGMENTS:number
The minimum abbreviation is ISE.

Comments
If you do not specify /SEGMENTS, the linker reserves enough storage
space to process up to 128 logical segments. If your program has
more than 128 logical segments, you must set the segment limit
higher to increase the number of logical segments LINK can process.
Set the segment limit lower if you get the following LINK error
message:
Requested segment limit too high
The number can be any integer value in the range 1 to 3072. It must
be a decimal, octal, or hexadecimal number. Octal numbers must
have a leading zero. Hexadecimal numbers must start with a leading
zero followed by a lowercase x; for example, Ox4B.

Example
This example sets the logical segment limit to 192:
LINK file/SE:192;

The following example sets the logical segment limit to 255 (X I FF'):
LINK moda+modb.run/SEGMENTS:0xff.ab.em+mlibfp;

8·29

SeHing the Stack Size

ISTACK

This option sets the program stack to the number of bytes given by
size. The linker automatically calculates the stack size of a program,
basing the size on the size of any stack segments given in the object
files. If you specify ISTACK, the linker uses the given size in place of
any value it may have calculated.

Format
ISTACK:size
The minimum abbreviation is 1ST.

Comments
The size can be any positive integer value in the range 1 through
65534. The value can be a decimal, octal, or hexadecimal number.
Octal numbers must begin with a zero. Hexadecimal numbers must
begin with a leading zero followed by a lowercase x; for example,

Ox1B.
The stack size can also be changed after linking with the EXEMOD
utility.

Examples
This example sets the stack size to 512 bytes:
LINK file/STACK:512;

The following example sets the stack size to 255 (X'FF') bytes:
LINK moda+modb,run/ST:GxFF.ab.\lib\start;

The following example sets the stack size to 24 (30 octal) bytes:
LINK startup+file/ST:G3G;

8-30

Reading the Map File
The map file lists the names, load addresses, and lengths of all segments in a program. It also lists the names and load addresses of
any groups in the program, the program's start address, and messages about any errors the linker may have encountered. If you use
the IMAP LINK option, the map file lists the names and load
addresses of all public symbols.
In the map file, segment information has the general form:
Start

Stop

Length

Name

Class

000e0H
e2B90H
0S092H
0S0A0H
0S210H
eS246H

e2B86H
eS091H
0Se92H
0S2eFH
0S24SH
eS761H

02B87H
02Se2H
0ee0eH
e0170H
00e36H
e0S1CH

_TEXT
EMULATOR_TEXT
C_ETEXT
EMULATOR_DATA
NULL
_DATA

CODE
CODE
ENDCODE
FAR_DATA
BEGDATA
DATA

The Start column shows the address of the first byte in the segment.
The number shown is the offset from the beginning of the program.
This number is referred to as the frame number. The Stop column
shows the address of the last byte in the segment. The Length is the
length of the segment in bytes. The Name column shows the name of
the segment and the Class column shows the class name of the
segment.
Group information has the general form:
Origin

Group

0S21:0

DGROUP

Program entry point at e000:e2Ae

If you have specified the IMAP LINK option, the linker adds a public
symbol list to the map file. Symbols are listed twice: first in alphabetical order, then in the order of their load addresses. This list has the
general form shown in the following example. (For each symbol
address, the number to the left of the colon represents a frame
number.)

8-31

Address

Publics by Name

0003:071A
0003:0718
0001: 287C
0003:0719
0001:0CF6

$i8_implicit_exp
$i8_inpbas
$i8_input
$i8_input_ws
$i8_output

Address

Publics by Value

0001:0010
0001:01B0
0001:0238
0001: 02A0
0001:0368

_main
_countwords
_analyze
_astart
_cintDIV

Creating an Overlaid Version of Your Program
You can direct LINK to create an overlaid version of your program..
This means that the COMMAND.COM loader will load parts of your
program only when they are needed, and these parts will share the
same space in storage. Your overlaid program should run in less
storage, but probably it will run more slowly because time is needed
to read and load the code into storage.
The use of overlays is restricted to object modules built with IBM
high-level languages that support overlays. Refer to the language
manuals that came with your compiler for a description of overlays.
Control is passed to overlay modules by a standard 8086-long (32-bit)
CAll/RETURN instruction. You cannot use long jumps or indirect
calls (through a function pOinter) to pass control to an overlay. When
a pOinter calls a function, the called function must be either in the
same overlay or in the root.

Specifying an Overlay Structure to LINK
You specify the overlay structure to the linker in response to the
Object Modules prompt. loading is automatic. You specify the overlays in the list of modules that you submit to the linker by enclosing
them in parentheses. Each parenthetical list represents one overlay.
For example:
Object Modules [.OBJ] : a+(b+c)+(e+f)+g+(i)

8-32

The elements (b+c), (e+f), and (i) are overlays. The remaining
modules, and any drawn from the run time libraries, make up the resident or root part of your program. LINK loads your program or root
overlays into the same region of storage, so only one can be resident
at a time. LINK does not allow duplicate names in different overlays,
so each module can occur only once in a program.
The linker replaces calls from the root to an overlay and calls from an
overlay to another overlay with an interrupt, followed by the module
identifier and offset. The DOS interrupt number used by LINK is 3FH.
You can change this interrupt number by specifying the
IOVERLAYINTERRUPT option. See "Using Linker Options" on
page 8-11 for more information.
LINK adds the name for the overlays to the .EXE file, and encodes the
name of this file into the program so the overlay manager can get
access to it.

How LINK Formats the .EXE File
This section is provided if you need to know how LINK uses IBM
Macro Assembler/2™ pseudo-up instructions to determine the format
of the .EXE file. Unlike high-level language compilers such as IBM
C/2 Compiler™,2 the IBM Macro Assembler does not check to determine if the 64KB physical segment limit of DOS 4.00 has been
exceeded.

Ordering Segments
LINK copies segments to the executable file in the same order that it
meets them in the object files. This order is maintained throughout
the program unless the linker finds two or more segments having the
same class, as defined by the SEGMENT pseudo-op instruction. Segments having identical classes are copied to the executable files as
contiguous blocks. The linker uses a segment's align-type defined in
the SEGMENT pseudo-op instruction to set the starting address for
the segment. The aUgn types are BYTE, WORD, PARA, and PAGE.

Macro Assembler/2 and C/2 Compiler are trademarks of the International
Business Machines Corporation.
8-33

These correspond to starting addresses at byte, word, paragraph, and
page boundaries, representing addresses that are multiples of 1, 2,
16, and 256, respectively. The default align-type is PARA.
When the linker encounters a segment, it checks the align-type before
copying the segment to the executable file. If the align-type is WORD,
PARA, or PAGE, the linker checks the executable image to see if the
last byte copied ends at an appropriate boundary. If not, LINK adds
extra null bytes to the image.

Segment Combine-Types
LINK uses combine-types that are defined in SEGMENT pseudo-op
instructions to determine whether two or more segments sharing the
same segment name should be one segment. The combine-types are
PUBLIC, STACK, COMMON, and PRIVATE.
• If a segment is combine-type PUBLIC, the linker combines it with
any segments of the same name and class. When LINK combines
segments, it makes the segments contiguous in storage; you can
reach each address in the segments using an offset from one
frame address. The result is the same as if the segments were
defined as a whole in the source file.
The linker preserves the align-type defined in the SEGMENT
pseudo-op·instruction for each code and data segment it adds to
the combined segment.
• If a segment is combine-type STACK, the linker combines individual segments as it does for PUBLIC combine-types. For
STACK segments, LINK copies an initial stack-pointer value to
the executable file. This stack-pointer value is the offset to the
end of the first STACK segment (or combined STACK segment)
that LINK meets. If you use the STACK type for STACK segments,
you need not give instructions to load the segment into the SS
register.
• If a segment is combine-type COMMON, the linker combines it
with any segments of the same name and class. When LINK combines COMMON segments, it places the start of each segment at
the same address. This creates a series of overlapping segments. The resulting combination segment has a length equal to
the longest individual segment.

8·34

• LINK assigns a default combine-type of PRIVATE to any segments
with no explicit combine-type definition in the source file. LINK
does not combine PRIVATE segments.
If LINK tries to combine segments that total more than 64KB, it displays an error message.

Groups
The GROUP pseudo-op instruction gives addressability to non- .
contiguous segments of various classes relative to the same frame
address. When LINK encounters a GROUP instruction, it adjusts all
storage references to items in the group to the same frame address.
Segments of a group need not be contiguous, belong to one class, or
have the same combine-type. However, all segments specified by the
GROUP must fit within 64KB of storage. If the group is smaller than
64KB of storage, LINK may place segments that are not part of the
group in the same storage area.
LINK does not specifically check that all segments in a group fit
within 64KB of storage. If the segments are larger than the 64KB
maximum, the linker can produce a fix-up overflow error.

Instruction and Data Reference Errors
Once the linker knows the starting address of each segment in a
program and establishes all segment combinations and groups, it
attempts to fix up any unresolved references to labels and variables.
The linker computes an appropriate offset and segment address and
replaces the temporary address values with the new values.
The size of the value that LINK computes depends on the type of reference. If LINK discovers an error in the anticipated size of the reference, it displays a fixup overflow error message. This happens, for
example, when a program tries to use a 16-bit offset to address an
instruction in a segment that has a different frame address. It also
occurs when the segments in a group do not fit within a single, 64K
block of storage.

8-35

LINK resolves four types of references:
• Short
• Near self-relative
• Near segment-relative
• Long.
A short reference occurs in JMP instructions that try to pass
control to labeled instructions in the same segment or group.
The target instruction must be no longer than 128 bytes from
the point of reference. The linker computes a signed, 8-bit
number for this short reference. It displays an error message
if the target instruction belongs to a different segment or
group (different frame address). The linker also displays an
error message if the distance from the frame address to the
target is more than 128 bytes in either direction.
A near self-relative reference occurs in instructions which
access data relative to the same segment or group. The
linker computes a 16-bit offset for this near self-relative reference. It displays an error message if the data resides in
more than one segment or group.
A near segment-relative reference occurs in instructions that
attempt to access data either in a specified segment or group
or relative to a specified segment register. LINK computes a
16-bit offset for this near segment-relative reference. It displays an error message if the offset of the target within the
specified frame is greater than 64KB or less than 0 bytes.
LINK also displays an error message if LINK cannot address
the beginning of the (canonical) frame of the target.
A long reference occurs in CALL instructions that try to get
access to an instruction in another segment or group. LINK
computes a 16-bit frame address and a 16-bit offset for this
long reference. The linker displays an error message if the
computed offset is greater than 64K or less than 0 bytes. The
linker also displays an error message if LINK cannot address
the beginning of the (canonical) frame of the target.

8-36

Linker Error Messages
This section lists error messages produced by the IBM Linker.
Fatal errors cause the linker to stop running. Fatal error messages
have the following format:

location: fatal error L1xxx: message text
Non-fatal errors indicate problems in the executable file. LINK
produces the executable file (and sets the error bit in the header if for
protected mode). Non-fatal error messages have the following
format:

location: error L2 xxx: message text
Warnings indicate possible problems in the executable file. LINK
produces the executable file (it does not set the error bit in the
header if -for protected mode). Warnings have the following format:

location: error L4xxx: message text
In these messages, location is the input file associated with the error,
or LINK if there is no input file.
If the input file is an .OBJ or .LlB file and has a module name, the
module name is enclosed in parentheses, as shown in the following
examples:
SLlBC.L1BLflle)
MAIN.OBJ(maln.c)
TEXT.OBJ
The following error messages may appear when you link object files
with LINK:

L1001
option: option name ambiguous
A unique option name does not appear after the option indicator
(I). For example, the command
LINK IN main;

8-37

produces this error, since LINK cannot tell which of the three
options beginning with the letter N is intended.

option: unrecognized option name
An unrecognized character followed the option indicator (/), as in
the following example:

L1002

LINK IABCDEF main;

option: MAP symbol limit too high
The specified symbol limit value following the MAP option is
greater than 32768, or there is not enough memory to increase
the limit to the requested value.

L1003

L1004 option : Invalid numeric value
An incorrect value appeared for one of the linker options. For
example, a character string is entered for an option that requires
a numeric value.

option : stack size exceeds 65534 bytes
The size you specified for the stack in the /STACK option of the
LINK command is more than 65534 bytes.

L 1006

option: Interrupt number exceeds 255
You gave a number greater than 255 as a value for the
/OVERLA YINTERRUPT option.

L1007

option: segment limit too high
The specified limit on the /SEGMENTS option is greater than
3072.

L1008

option: CPARMAXALLOC: illegal value
The number you specified in the /CPARMAXALLOC option is not
in the range 1 to 65535.

L1009

no object modules specified
You did not specify any object-file names to the linker.

L1020

cannot nest response flies
A response file occurs within a response file, which DOS 4.00
does not permit.

L 1021

response line too long
A line in a response file is longer than 127 characters.

L1022

terminated by user
You entered Ctrl + C.

L1023

8-38

L1024 nested right parentheses
You typed the contents of an overlay incorrectly on the command
line.
L1025 nested left parentheses
You typed the contents of an overlay incorrectly on the command
line.
L1026 unmatched right parenthesis
A left parenthesis is missing from the contents specification of an
overlay on the command line.
L1027 unmatched left parenthesis
A right parenthesis is missing from the contents specification of
an overlay on the command line.
L1041
resident-name table overflow
The total length of all resident names, plus three bytes per name,
is greater than 65534.
L1042 nonresident-name table overflow
The total length of all nonresident names, plus three bytes per
name, is greater than 65534.
L1043 relocation table overflow
There are more than 65536 load-time relocations for a single
segment.
L1045 too many TYPDEF records
An object module contains more than 255 TYPDEF records.
These records describe communal variables. This error can only
appear with programs produced by compilers that support communal variables.
L1046 too many external symbols In one module
An object module specifies more than the limit of 1023 external
symbols. You need to break the module into smaller parts.
L1047 too many group, segment, and class names In one module
The program contains too many group, segment, and class
names. You need to reduce the number of groups, segments, or
classes, and recreate the object files.
L1048 too many segments In one module
An object module has more than 255 segments. Split the module
or combine segments.

8-39

L1049 too many segments
The program has more than the maximum number of segments.
The SEGMENTS option specifies the maximum allowed number;
the default is 128. Relink using the /SEGMENTS option with an
appropriate number of segments.
L1050 too many groups In one module
The linker found more than 21 group definitions (GRPDEF) in a
single module. Reduce the number of group definitions or split
the module.
L1051
too many groups
The program defines more than 20 groups, not counting
DGROUP. Reduce the number of groups.
L1052 too many libraries
An attempt is made to link with more than 32 libraries. Combine
libraries, or use modules that require fewer libraries.
L1053 symbol table overflow
The program has more than 256K bytes of symbolic information,
(such as public, external, segment, group, class, and file names).
Combine modules or segments and recreate the object files.
Eliminate as many public symbols as possible.
L1054 out of memory: reduce # In ISEGMENTS: # or IMAP: #
The linker does not have enough memory to allocate tables
describing the number of segments requested. (The default is
128 or the value specified with the /SEGMENTS option.) Try
linking again using the /SEGMENTS option to select a smaller
number of segments (for example, use 64 if the default was used
previously), or free some memory by eliminating resident programs or shells.
L1056 too many overlays
The program defines more than 63 overlays.
L1057 data record too large
A LEDATA record (in an object module) contained more than 1024
bytes of data. This is a translator (compiler or assembler) error.
Note which translator (compiler or assembler) produced the
incorrect object module and the Circumstances, and contact your
authorized IBM dealer.
L1070 segment size exceeds 64K
A single segment contains more than 64KB of code or data. Try
compiling, or assembling, and linking using the large model.
8-40

L1071
segment _TEXT larger than 65520 bytes
This error is likely to occur only in small-model C programs, but it
can occur when any program with a segment named _TEXT is
linked using the IDOSSEG option of the LINK command. Smallmodel C programs must reserve code addresses 0 and 1; this is
increased to 16 for alignment purposes.
L1072 common area longer than 65536 bytes
The program has more than 64KB of communal variables. This
error cannot appear with object files produced by the IBM Macro
Assembler/2. It occurs only with programs or other compilers
that support communal variables.
L1073 file-segment limit exceeded
There are more than 255 physical or file segments.
L1074 name: group larger than 64KB
A group contained segments which total more than 65536 bytes.
L1075 entry table larger than 65535 bytes
You have exceeded a linker table size limit because of too many
entry names. Reduce the number of names in the modules you
are linking.
L1080 cannot open list file
The disk or the root directory is full, or an invalid filename was
entered. Delete or move files to make space, or link again with a
valid fi lename.
L1081
out of space for run file
The disk on which .EXE file is being written is full.
Free more space on the disk and restart the linker.
L1083 cannot open run file
The disk or the root directory is full. Delete or move files to make
space.
L1084 cannot create temporary file
The disk or root directory is full. Free more space in the directory
and restart the linker.
L1085 cannot open temporary file
The disk or the root directory is full. Delete or move files to make
space.

8-41

L1086 scratch file missing
Internal error. You should note the conditions when the error
occurs and contact your authorized IBM Computer dealer.
L1087 unexpected end-of-flle on scratch file
The disk with the temporary linker-output file is removed.
L1088 out of space for list file
The disk on which the listing file is being written is full. Free
more space on the disk and restart the linker.
L1089 filename: cannot open response file
The linker could not find the specified response file. This usually
indicates a typing error. Correct the error.
L1090 cannot reopen list file
The original disk is not replaced at the prompt. Restart the linker.
L1091
unexpected end-of-flle on library
The disk containing the library probably was removed. Replace
the disk containing the library and run the linker again.
L1093 filename: object file not found
The linker could not find the specified object file.
Invalid object module
L1101
One of the object modules is not valid.
If the error persists after recompiling, contact your authorized
IBM dealer.
L1102 unexpected end-of-flle
An invalid format for a library was found.
L1103 attempt to access data outside segment bounds
A data record in an object module specified data extending
beyond the end of a segment. This is a translator error. Note
which translator (compiler or assembler) produced the incorrect
object module and the Circumstances, and contact your authorized IBM dealer.
L1104 filename : not valid library
The specified file is not a valid library file. This error causes the
linker to stop running.
L1113 unresolved COMDEF; Internal error
You should note the conditions when the error occurs and contact
your authorized IBM dealer.

8-42

L1114 file not suitable for IEXEPACK; rellnk without
For the linked program, the size of the packed load image plus
the packing overhead is larger than that of the unpacked load
image. Relink without the EXEPACK option.
L2001
flxup(s) without data
A FIXUP record occurred without a data record immediately preceding it. This is probably a compiler error.
L2002 flxup overflow number In frame seg segname target seg
segname target offset number
The following conditions can cause this error:

• A group is larger than 64KB.
• The program contains an intersegment short jump or intersegment short call.
• The name of a data item in the program conflicts with that of a
subroutine in a library included in the link.
• An EXTRN declaration in an assembler-language source file
appeared inside the body of a segment.
This example may cause this error:
code
start
start
code

SEGMENT
EXTRN
PROC
call
ret
ENDP
ENDS

public 'CODE'
main:far
far
main

The following construction is preferred:
code
start
start
code

EXTRN
SEGMENT
PROC
call
ret
ENDP
ENDS

main:far
public 'CODE'
far
main

Revise the source file and recreate the object file.
L2003 Intersegment self-relative flxup
An intersegment self-relative fixup is not allowed.
L2004
LOBYTE-type flxup overflow
A LOBYTE fixup produced an address overflow.

8-43

L2005 flxup type unsupported
A fixup type occurred that is not supported by the linker. This is
(probably) a compiler error. You should note the conditions when
the error occurs and contact your authorized IBM dealer.
L2010 too many flxups In LlDATA record
There are more fixups applying to a LlDATA record than will fit in
the linker's 1024-byte buffer. The buffer is divided between the
data in the LlDATA record and run-time relocation items, which
are eight bytes apiece, so the maximum varies from 0 to 128. This
is probably a compiler error.
L2011
name: NEAR/HUGE conflict
Conflicting NEAR and HUGE attributes are given for a communal
variable. This error can occur only with programs produced by
compilers that support communal variables.
L2012 name: array-element size mismatch
A far communal array is declared with two or more different
array-element sizes (for example, an array declared once as an
array of characters and once as an array of real numbers). This
error cannot occur with object files produced by the IBM Macro
Assembler/2. It occurs only with compilers that support far communal arrays.
L2013 LlDATA record too large
A LlDATA record in an object module contains more than 512
bytes of data. Most likely, an assembly module contains a very
complex structure definition or a series of deeply-nested DUP
operators. For example, the following structure definition causes
this error:
alpha

16DUP(11 DUP(12 DUP(13 DUpe •.• »»

Simplify the structure definition and reassemble. (LIDATA is a
DOS term.)
L2024 name: symbol already defined
One of the special overlay symbols required for overlay support
is defined by an object.
L2025 name: symbol defined more than once
Remove the extra symbol definition from the object file.
L2028 automatic data segment plus heap exceed 64K
The size of DGROUP near data plus requested heap size is
greater than 64K.

8-44

L2029
unresolved externals
One or more symbols are declared to be external in one or more
modules, but they are not publicly defined in any of the modules
or libraries.
A list of the unresolved external references appears after the
message, as shown in the following example:

exit in file(s)
-main.obj (main.c)
_fop en in files(s)
fileio.obj(fileio.c) main.obj(main.c)

The name that comes before In flle(s) is the unresolved external
symbol. On the next line is a list of object modules that have
made references to this symbol. This message and the list are
also written to the map file, if one exists.
L2030
starting address not code (use class 'CODE')
You specified to the linker a starting address which is a segment
that is not a CODE segment. Reclassify the segment to CODE, or
correct the starting point.
L4001
frame-relative flxup, frame Ignored
A fixup occurred with a frame segment different from the target
segment where either the frame or the target segment is not
absolute.
L4002 frame-relative absolute flxup
A fixup occurred with a frame segment different from the target
segment where both frame and target segments were absolute.
L4012
load-high disables EXEPACK
You must select either the IHIGH or EXEPACK option. They
cannot be used together.
L4014
Invalid option for old-format executable file Ignored
If a DOS 4.00 format program is produced, the options IALlGNMENT, INOFARCALLTRANSLATION, and IPACKCODE are meaningless, and the linker ignores them.
L4020
name: code-segment size exceeds 65500
Code segments of length 65501 through 65536 may be unreliable
on the 80286 processor.

8-45

L4021
no slack segment
The program does not contain a stack segment defined with
STACK combine type. This message should not appear for
modules whose source code was compiled by the high-level language compilers supported by DOS 4.00, but it could appear for
an assembler-language module. Normally, every program
should have a stack segment with the combine type specified as
STACK. You can ignore this message if you have a specific
reason for not defining a stack, or for defining one without the
STACK combine type.
L4022 name1, name2 : groups overlap
Two groups are defined so that one starts in the middle of
another. This may occur if you defined segments in an assembly
file and did not correctly order the segments by class.
L4028
name: segment already defined
A segment is defined more than once with the same name. Segments must have unique names for the linker. Only the first definition of a name is recognized.
L4029 name: DGROUP segment converted to type data
A segment which is a member of DGROUP is defined as type
CODE in an object file.
L4030 name: segment attributes changed to conform with automalic dala segment
The segment named name is defined in DGROUP, but the shared
attribute is in conflict with the instance attribute. For example,
the shared attribute is NONSHARED and the instance is SINGLE,
or the shared attribute is SHARED and the instance attribute is
MULTIPLE. The bad segment is forced to have the right shared
attribute and the link continues. The image is not marked as
having errors.
L4031
name: segment declared In more than one group
A segment is declared to be a member of two different groups.
Correct the source file and recreate the object files.
L4032 name: code-group size exceeds 65500 bytes
Code segments of length 65501 through 65536 may be unreliable
on the 80286 processor.
L4034 more than 239 overlay segments; extra put In rool
You specified an overlay structure containing more than 239 segments. The extra segments have been assigned to the root
overlay.
8-46

L4036 no automatic data segment
No group named DGROUP is declared.
L4050 too many public symbols
The IMAP option is used to request a sorted listing of public
symbols in the map file, but there were too many symbols to sort.
(The default is 2048 symbols.) The linker produces an unsorted
listing of the public symbols. Relink using IMAP:number.
L4051
filename: cannot find library
The linker could not find the specified file. Enter a new filename,
a new path specification, or both.
L4053 VM.TMP: Illegal file name; Ignored
VM.TMP appears as an object-file name. Rename the file and
rerun the linker.
L4054 filename: cannot find file
The linker could not find the specified file. Enter a new filename,
a new path specification, or both.

8-47

Linker Limits
The table below summarizes the limits imposed by the linker.
However, your program may be adjusted so that the linker will set
aside its limits to accommodate it.

Item

Limit

Symbol table

256KB

Load-time relocations

Default is 32KB. If IEXEPACK is used,
the maximum is 512KB.

Public symbols

The range 7700 through 8700 can be
used as a guideline for the maximum
number of public symbols allowed; the
actual maxi mum depends on the
program.

External symbols per
module

1023

Groups

Maximum number is 21, but the linker
always defines DGROUP so the effective
maximum is 20.

Overlays

Segments

128 by default; however, this maximum
can be set as high as 3072 by using the
ISEGMENTS option of the LINK
command.

Libraries

Group definitions per
module

Segments per module

255

Stack

64KB

8-48

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
followi ng format:

9-1

drive

path

EXE2BIN

\
drive

path

filename

.ext

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.

9·2

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:
symboll db "e:\filename".a
symbo12 dw SEG symboll :explicit use of SEG
symbol 3 dw symboll
:implicit use of OFFSET
• You have used a segment name as an immediate field of instruction:
myseg

SEGMENT

MOV

AX.MYSEG

PUBLIC
; 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 laaH
START
END START

9-3

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 relocatabl€..
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.

9-4

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:

\ drive

J "" path 7

DEBUG

\a drive 7 '= path 7\ filename
"-.ext

I·

• \a parm1 J "" parm2 J
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.
10-1

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:
des: 100 ll0
des: 100 110
d.es: 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:
des: 100 CS: 100
"'error 110

In this example, the Dump command expects the second address to
contain only a hexadecimal offset value. It finds the 5, which is not a
hexadecimal character.

10-2

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-6.
Command

Task Description

A (Assemble)

Assemble IBM Macro Assembler statements
directly into memory.

C (Compare)

Compare the contents of two blocks of
memory.

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.

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.

10-3

Command

Task Description

P (Proceed)

Execute a subroutine call, loop instruction,
interrupt, or repeat string instruction and
return control to DEBUG at the next instruction.

Q (Quit)

End the DEBUG session without saving the
debugged program.

R (Register)

Display the contents of registers and the settings of flags.

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 (Unassemble)

Translate the contents of memory into
Assembler-like 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)

Allocate a specified number of expanded
memory pages to an EMS handle.

XD (Deallocate)

Deallocate an EMS handle.

XM (Map)

Map an EMS logical page to an EMS physical
page from an EMS handle.

XS (Status)

Display the status of expanded memory.

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 (eS, OS, 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.

10-4

• 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, ex, OX, BP, SI, and 01) are set
to O. However, if you start the DEBUG program with a file specification, the ex register contains the length of the file in bytes. If
the file is greater than 64KB, the length is contained in registers
BX and ex (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 Flies
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 OS and
ES registers, however, point to the program segment prefix at the
lowest available segment. The BX and ex 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 Flies
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.

10-5

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 ttle Enter key when you are prompted for the next statement to
return to the DEBUG prompt.
DEBUG responds to invalid statements by displaying:

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.
10·6

A (Assemble) Command
• The segment override mnemonics are CS:, OS:, 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:0S00 JMP S02 ;a 2 byte short jump
0100:0S02 JMP NEAR S0S ;a 3 byte near jump
0100:0S0S JMP FAR S0A ;a S 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
DEC

BYTE PTR [128]
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
MOV

AX.21 ;Load AX with 21H
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
DB
DB

1.2.3.4."THIS IS AN EXAMPLE"
'THIS IS A QUOTE: "'
"THIS IS AN APOSTROPHE: '"

1000.2000.3000. "BACH:

10-7

A (Assemble) Command
• All forms of the register indirect commands are supported. For
example:
ADD BX.34 [BP+Z] [SI-l]
POP [BP+DI]
PUSH [SI]
• All opcode synonyms are supported. For example:
LOOPZ 100
LOOPE 100
JA
JNBE

Z00
Z00

• For numeric co-processor opcodes the WAIT or FWAIT prefix
must be explicitly specified. For example:
FWAIT FADD ST.ST(3)
FLO TBYTE PTR [BX]

Example
C>debug
-aZ00
0SB4:0Z00 xor ax.ax
0SB4:0Z0Z mov [bx].ax
0SB4:0Z04 ret
0SB4:0205

10·8

:This 1ine will
:assemble a
:FWAIT prefix
:This line will
:not

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:
addrl bytel 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 OS register. To
specify an ending address for range, enter it with only an offset value.
10-9

C (Compare) Command
Example
C lee L2e 2ee
The 32 bytes (hex 20) of memory beginning at 08:100 are compared
with the 32 bytes beginning at 08:200. L20 is the range.

10-10

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.

10-11

D (Dump) Command
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:

o address
or

o
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 OS register.

10-12

D (Dump) Command
Option 2
Use this option to display the contents of the specified address range.
For example:
Orange

Note: If you enter only an offset for the starting address, the D
command assumes the segment contained in the OS register.
If you specify an ending address, enter it with only an offset
value.
For example:

o c5:190

l0C

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

10-13

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

list

A stri ng of byte val ues. If you i ncl ude 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.
IIThese IIl1quotes are correct.1I
'This onel's okay. too.
llll

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

10-14

E (Enter) Command
For example:
E ds:100 F3 "xyz" 80

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 anyone 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.

10-15

E (Enter) Command
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. 0a.

BC._

To change the contents of the current location (04BA:0103) from hex
Be 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.0a. BC.4204BA:0102 00.04BA:0101 10.6F_

Press the Enter key to end the Enter command. The hyphen prompt
will appear.

10-16

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 stri ng of byte val ues. If you i ncl ude 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 OS
register.

10-17

F (Fill) Command
Example
F 4BA:199 L 5 F3 "XYZ" 80

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 5859 5A 80.

10·18

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.
10-19

G (Go) Command
Option 2
This option performs the same function as Option 1 but, in addition,
aHows 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 anyone 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.
Noles:
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).

10-20

G (Go) Command
For example:
G 102 1EF 200

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, aU three breakpoints are
removed, the display occurs, and the Go command ends.
Refer to the Register command for a description of the display.

10-21

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 GF 8

Ga17 aaa7
The hexadecimal sum of OOOF and 0008 is 0017, and their difference is
0007.

10-22

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

The single hexadecimal byte read from port 02F8 is displayed (68).

10-23

L (Load) Command

Purpose
Loads a file or absolute disk sectors into memory.

Format
L [address[drive sector sector]]

Parameters
address

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 O. 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 redisplay the Load command. Then press the Enter key.

10-24

L (Load) Command
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 C5 register.
For example, to load data, you might enter:
L OS:lee 1 eF 60

The data is loaded from the diskette in drive 8 and placed in memory
beginning at 05:100. Consecutive sectors of data are transferred,
60H (109), starting with relative sector hex OF (15) (the 16th sector on
the diskette).
Note: Option 1 cannot be used if the drive specified is a network
drive.

10-25

L (Load) Command
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

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-4 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.

10·26

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

address

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.

10-27

M (Move) Command
Notes:
1. If you enter only an offset for the beginning address of the range,
the M command assumes the segment contained in the OS 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 OS register.

Example
MCS:lee Lie see
The 17 bytes of data from CS:100 through CS:110 are moved to the
area of memory beginning at OS:500.

10-28

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 fil el fil e2

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
10-29

N (Name) Command
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 OC).

10-30

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

10-31

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

value

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 PO is the same as specifying TO.

Example
If the following instructions are executed:
elee
el03

CALL
JC

Ieee
zoee

Ieee

XOR

AX.AX

lXXX

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.

10·32

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>

10-33

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
BX

SP
BP
SI

IP
F

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-4.)
Display a Single Register
To display the contents of a single register, enter the register name:
RAX
The system might respond with:
AX FlE4

10·34

R (Register) Command
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 FlE4
:FFF_

Now, pressing the Enter key changes the contents of the AX register
to hex OFFF.
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=aEaa 8x=aeFF cx=eae7 ox=elFF sp=e390 8P=eeea SI=ee5C OI=eeee
OS=3D58 ES=3D58 SS=3D5B CS=3D5B IP=GIIA NV UP EI PL NZ NA PO NC
3058:GIIA C02l
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

10-35

R (Register) Command
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)

Direction (decrease/increase)

Interrupt (enable/disable)

Sign (negative/positive)

Zero (yes/no)

Parity (even/odd)

Carry (yes/no)

Auxiliary

l~arry

(yes/no)

To display all flags, enter:
RF

If all the flags are in a set condition, the response is:
OV ON 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 ON EI NG ZR AC PE CY - PONZOINV

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.

10-36

R (Register) Command
If you want to see if the new codes are in effect, enter:
RF

The response is:
NV ON OI 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.

10-37

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.
IIThese 1111 quotes II II are correct. II
'This one I IS okay, too. I

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.
Nole: If you enter only an offset for the starti ng address of the range,
the S command assumes the segment contained in the OS register.

10-38

S (Search) Command
Example
If you want to search the range of addresses from CS:100 through
CS:110 for hex 41, type:
S CS: lee 11e 41

If two matches are found the response might be:
e4BA:e1e4
04BA:e1eo

If you want to search the same range of addresses for a match with
the 4-byte list (41 "AB" E), enter:
S CS: 10e l 11 41 "AB" E

The starting addresses of all matches are listed. If no match is found,
no address is displayed.

10-39

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

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).

10-40

T (Trace) Command
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,OEH), this may be displayed:
AX=eEee Bx=eeFF cx=eee7 Dx=e1FF sp=e39D BP=eeee SI=eesc DI=eeee
OS=30SB ES=30SB SS=30SB CS=30SB IP=e11C NV UP EI PL NZ NA PO NC
30SB:e11C C021
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 1e
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.

10-41

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:
94BA:9199 296472
94BA:9193 FC
94BA:9194 7665

AND [SI+72].AH
CLD

JBE 916B

Format
U [address]
or
U [range]

Parameters
address

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 l10.
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.

10-42

U (Unassemble) Command
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.
10-43

U (Unassemble) Command
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
04BA:0103
94BA:0104
94BA:0106

206472
FC
7665
207370

AND [SI+72].AH
CLD
JBE e16B
AND [BP+DI+70].DH

The same display appears if you enter:
U e4BA:1ee L 7

or
U 04BA: lee L 8

or
U e4BA:1ee L 9

10-44

W (Write) Command

Purpose
Writes the data being debugged to disk.

Format
W [address [drive sector sector]]

Parameters
address

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.
Nole: Relative sector numbers are obtained by counting
the sectors on the disk surface. The fi rst sector
on the disk is at track 0, sector 1, head 0, and is
relative sector O. The numbering continues for
each sector on that track and head, then conti nues with the fi rst 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 fi rst 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.

10-45

W (Write) Command
The Write command has two format options.

Opllon 1
Use this option to write data to disk beginning at a specified address.
For example:
Waddress 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).

Noles:
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 IFD 1 10a 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 OA (10)
sectors.

Opllon 2
This option permits you to use the WRITE command without specifying parameters or specifying only the address parameter. For
example:
W

or
Waddress
10-46

W (Write) Command
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.
Nole: 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.

10-47

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:
XA2

If two pages of memory are available, a message like this is displayed:
Handle created = eeeE

10-48

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 GaGE

If the handle deallocation is successful, you receive a message like
this:
Handle GaGE deallocated.

10-49

XM (EMS Map) Command

Purpose
Maps an EMS logical page to an EMS physical page from an EMS
handle.

Format
XM Ipage ppage handle

Comments
The Ipage 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

If the mapping is successful, you receive this message:
Logical page

10-50

mapped to physical page

ee.

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.

10-51

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 0/01

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.

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 wrlHen

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.

10-52

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.

10-53

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.

10-54

Chapter 11. Writing an Installable Device
Driver
This chapter provides guide and system architecture information to
support successful creation of an installable device driver.
We recommend you use the information provided in this chapter in
conjunction with the information provided in the VDISK.ASM file on
the utilities diskette. This file contains the fully documented source
code for the VDISK device driver, which emulates a fixed disk in
RAM.
Note: The example on the utilities diskette does not reflect the
current level of VDISK.SYS ..

Types of Device Drivers
A device driver is a memory image file or an .EXE file that contains
the code needed to implement a device. DOS 4.00 allows two types
of device drivers to be installed:
• Character device drivers
• Block device drivers.

Character Device Drivers
Character device drivers perform character 110 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 1/0 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.
11-1

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-4
"Build BPB Request" on page 11-16
"Input and Output Requests" on page 11-20.

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=driverl

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
11-2

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 install able 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

11-3

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.
AHrlbute 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.

11-4

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 O.
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.
11-5

Blt2
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.

11-6

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

a-BYTE

Data

VARIABLE

Length Field

The length field identifies the length of the request header and subsequent data in bytes.
11·7

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-9 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-23 and
"Removable Media Request" on page 11-25 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.

11-8

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
00

01
02

03
04

05
06
07
08
09

OA
08

OC
OD

OE
OF

Meaning
Write protect violation
Unknown unit
Device not ready
Unknown command
CRC error
Bad drive request structure length
Seek error
Unknown media
Sector not found
Printer out of paper
Write fault
Read fault
General failure
Reserved
Reserved
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.

11-9

Command
Code

Request
Description

Device
Type

Initialization

Both

Media check

Block

Build BPB

Block

IOCtl input (called only if bit 14 of
attribute is set to 1)

Both

Input (read)

Both

Nondestructive input no wait

Character

Input status

Character

Input flush

Character

Output (write)

Both

Output (write with verify)

Block

Output status

Character

Output fl ush

Character

IOCtl output (called only if bit 14
of attribute is set to 1

Both

Device open (called only if bit 11
of attribute is set to 1)

Both

Device close (called only if bit 11
of attri bute is set to 1)

Both

Removable media (called
1 1 1 1 1 x x x
bits - >
7 6 5 4 3 2 1 0

Bit

0
1
2

3-7

Meaning
1 =2-sided
1 =8 sector
1 = removable
must be set to 1

0= not 2-sided
0= not 8 sector
0= not removable

Note: An exception to the above is that the media descriptor byte
value of FO, 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
Type

Sides

Sectorsl
Track

Media
Descriptor

Fixed disk

F8H

5.25 inch

F9H

5.25 inch

FCH

5.25 inch

FOH

5.25 inch

FEH

11-14

Sectorsl
Track

Media
Descriptor

Disk
Type

5.25 inch

FFH

8 inch

FEH

8 inch

FDH

8 inch

FEH

3.5 inch

F9H

3.5 inch

FOH

Sides

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 FOH 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-i nch 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.

11-15

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 10 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:

11-16

Field

Length

A 2-byte short JMP instruction (EBH), followed by a
NOP instruction (90H).

WORD

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

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, FAT areas, and directories

WORD

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.

11-17

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

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 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.

WORD

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 used to define a partition that is greater
than 32MB, or one that crosses the 32MB boundary.

DWORD

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).

11-18

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 instruction (90H).

WORD

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 OH 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.

11-19

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 number. This entry has no meaning for a
character device.)

WORD

For DOS 3.0 to DOS 4.00, pointer to the volume
identification if error code OFH is returned

DWORD

Starting 32-bit sector number. (Use this entry to the
block device driver with the attribute bit 1 set.)

DWORD

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.

11-20

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 OFH (Invalid Disk Change), it
must provide a OWORO pointer to an ASCIIZ string identifying the
correct volume 10 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
OFH. If there are no open files (reference count=O) and the disk has
been changed, the 110 is valid, and error OFH is not returned. If there
are open files (reference count> 0) and the disk has been changed,
an error OFH situation may exist. DOS 4.00 IBMOOS.COM will
request an OPEN or CLOSE function only if SHARE is loaded.

11-21

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.

11-22

Character Input and Output Status Requests
Command Codes = 6, 10

I Field

Length
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 typeahead 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.

11-23

Character Input and Output Flush Requests
Command Codes = 7, 11

I Field

Length
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.

11-24

Open and Close Requests
Command Codes = 13, 14

I Field

Length
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 fl ush 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 1/0 stream.
Similarly, the CLOSE call can send a post string, such as a form feed,
at the end of an 1/0 stream.
Using 10Cti to set the preliminary and ending strings provides a flexible mechanism for serial 1/0 device stream control.

Removable Media Request
Command Code = 15

I Field

Length
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 10Cti function call
(44H).

11·25

This call is useful because it notifies a utility if it is dealing with a
removable or non removable 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 non removable. If the busy bit is 0, the
media is removable.
No error bit checking is performed. It is assumed that this call always
succeeds.

11-28

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 10CTL request packet

DWORD

The driver must:
• Support the functions described under Generic 10Cti request
• Maintain its own track table (TrackLayout).
See Appendix C, "1/0 Control for Devices (IOCtl)" on page C-1 for a
description of the functions provided by generic 10Cti requests.

11·27

Get Logical Device Request
= 23

Command Code
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

11·28

CLOCKS 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 CLOCKS 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
CLOCKS device gets the date and time; writing to it sets the date and
time.

11-29

11·30

Part 3. Appendixes

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 BOH 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 31 H (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.

21 H Function Request
Refer to each function call issued within 21H in Appendix B, "DOS
4.00 Function Calls" on page B-1.

A-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 OAH,
then A 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.

A-2

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-7.
The registers are set up for a retry operation, and an error code is in
the lower half of the 01 register with the upper half undefined. The
error codes follow:
Error Code

o
1
2
3

4
5
6
7

8
9
A
B
C

Meaning
Attempt to write on write-protected diskette
Unknown unit
Drive not ready
Unknown command
Data error (CRC)
Bad request structure length
Seek error
Unknown media type
Sector not found
Printer out of paper
Write fault
Read fault
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

es
FLAGS

AX
BX

User registers at time of original
INT 21H request

ex
DX
SI
A-3

BP
DS
ES

IP
CS

From the original interrupt 21 H
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
originallNT 24H vector saved in step 1.
3. DOS 4.00 gives the appropriate prompt, and waits for the user
input (Abort, Retry, Failor 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

A-4

registers from the stack. Control can then be passed to the
desi red poi nt.
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)
o 0 DOS 4.00 area
o 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).

A-5

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 01 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 routi ne is entered ina 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 OCH, 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 21 H 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 OCH 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=O) are converted to FAIL for critical errors
that occur on FAT or DIR sectors.

A-6

9. Refer to "Responding to Errors" on page B-6 and "Extended
Error Codes" on page B-7 for information on how to obtain additional error information.
10. For DOS 4.00, IGNORE requests (AL=O) 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 desi red, 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.

A-7

The request for extended 25H or 26H is:
MOV

LDS
MOV
INT
POP
JC
PACKET LABEL
DD
DW
DD

AL,DRIVE

BX,PACKET
CX,-l
25H or 26H
AX
ERROR
BYTE
RBA
COUNT
BUFFER

; Drive number to process

; e =A
;
;
;
;
;
;
;

1 =B
2 = C •••
Parameter list
Indicates extended format
Issue request to DOS 4.00
Discard stack word
Error code returned in AX

;
;
;
;
;

Control packet
RBA of first sector
(0 origin)
Number of sectors to I/O
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 O. 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
A-8

in the low byte of 01 when an interrupt 24H is issued, and (AH)
contains:
80H
40H
08H
04H
03H
02H

Attachment failed to respond
SEEK operation failed
Bad CRC on diskette read
Requested sector not found
Write attempt on write-protected diskette
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 21 H Generic IOCTL (AH = 44H), with a
request to return the BPB that BUILD BPB returns; or an INT 21 H Get
Current Directory (AH = 47H).

27H Terminate but Stay Resident
This vector is used by programs that are to remai n 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 OX to its last address
plus one, relative to the program's initial OS 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.

A-9

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 call4CH 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 31 H).
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 = OOH through BFH are reserved for DOS
4.00. Applications should use multiplex numbers COH 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.

A-10

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

Get installed state

Submit file

Cancel file

Cancel all files

Status

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

Invalid function

File not found

Path not found

Too many open files

Access denied

A-11

Error
Codes

Description

Queue full

Busy

Name too long

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=O, AH = 1. On return, AL contains the installed state as
follows:
AL=O

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 O. 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.

A-12

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, OX 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 O. 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 retu rn, AX contai ns the error codes.
For information on the error codes returned, refer to "Print Error
Codes" on page A-11.
AL=FB-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.
A-13

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.
BII

Function In effect If bll is on

APPEND enabled

IPATH

Nole: 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 = 11 H 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 21 H 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

A-14

Interrupt 21 H, it resets the Return Found Name state. An example of
this process follows:
MOV
MOV
INT
CMP
JE

AH.0B7H
AL.0
2FH
AL.0
NOT_INSTALLED

; Indicate APPEND
; Get installed state

MOV
MOV
INT
CMP

AH.0B7H
AL.2
2FH
AX.-1
PC_LAN_APPEND

Indicate APPEND
Get APPEND version

; APPEND installed?

DOS version?
; AX<> -1 means PC LAN

JNE
APPEND
The following functions are valid only if DOS 4.00 APPEND
MOV
MOV
INT

AH.0B7H
AL.4
2FH

Indicate APPEND
Get APPEND path pointer
ES:DI = address of APPEND path
(Buffer is 128 characters long)

MOV
MOV
INT

AH.0B7H
AL.6
2FH

Indicate APPEND
; Get function state
;
;
;
;
;
;
;

BX = function state
8000H = IX is on
4000H = IE is on
2000H = IPATH is on
0a01H = APPEND enabled
If off. similar to null
APPEND path
Set on by any non-status
occurrence of APPEND

MOV
MOV
MOV
INT

AH.0B7H
AL.7
BX.state
2FH

Indicate APPEND
Set function state
New state

MOV
MOV

AH.0B7H
AL.llH

Indicate APPEND
Set Return Found
Name state

INT

2FH

A-15

Example 2FH Handler

MYNUM

INT_2 F_N EXT
INT_2F:

x ; x = The

specific AH
; multiplex number.
? ; Chain location

ASSUME DS:NOTHING.ES:NOTHING.SS:NOTHING
CMP
JE
JMP

AH.MYNUM
MINE
INT_2F_NEXT

Chain to next
2FH Handler

MINE:
CMP
JB
I RET

AL.0F8H
DOJUNC
IRET on reserved
functions

DOJUNC:
OR
JNE

AL.AL
NON_INSTALL

MOV
IRET

AL.0FFH

A-16

;
;
;
;

Non Get Installed
State request
Say 11m here
All done

Installing the Handler
The following example contains the functions necessary to install a
handler:

HOV
XOR
INT

AH.MYNUM
AL.AL
2FH

OR
JZ

AL.AL
OK_INSTALL

BAD_INSTALL:
OK_INSTALL:

; Ask if already
; installed

; Handler already installed .sp 3
; Install my
; handler

HOV
MOV
INT

AL.2FH
AH.GET_INTERRUPT VECTOR
21H

MOV
HOV
MOV
MOV
MOV
INT

WORD PTR INT_2F NEXT+2.ES
WORD PTR INT_2F_NEXT.BX
DX.OFFSET INT_2F
AL.2FH
AH.SET_INTERRUPT_VECTOR
21H
: Set multiplex
: vector

: Get multiplex
; vector

30H-3FH Reserved for DOS 4.00
These interrupts are reserved for DOS 4.00 use.

A·17

A·18

Appendix B. DOS 4.00 Function Calls
Number
OOH
01H
02H
03H
04H
05H
06H
07H
08H
09H
OAH
OBH
OCH
ODH
OEH
OFH
10H
11H
12H
13H
14H
15H
16H
17H
18H
19H
1AH
1BH
1CH
.. 1O.H

1EH
1FH
20H
21H
22H
23H
24H
25H

Function Name
Program terminate
Console input with echo
Display output
Auxiliary inpJt
Auxiliary output
Printer output
Direct console 110
Direct console input without echo
Console input without echo
Display string
Buffered keyboard input
Check standard input status
Clear keyboard buffer, invoke a keyboard function
Disk reset
Select disk
Open file
Close file
Search for fi rst entry
Search for next entry
Delete file
Sequential read
Sequential write
Create file
Rename file
Reserved by DOS 4.00
Current disk
Set disk transfer address
Allocation table information
Allocation table information for specific device
Reserved by DOS 4.00
Reserved by DOS 4.00
Reserved by DOS 4.00
Reserved by DOS 4.00
Random read
Random write
File size
Set relative record field
Set interrupt vector
8-1

26H
27H
28H
29H
2AH
2BH
2CH
2DH
2EH
2FH
30H
31H
32H
33H
34H
3SH
36H
37H
38H
39H
3AH
3BH
3CH
3DH
3EH
3FH
40H
41H
42H
43H
44H
45H
46H
47H
48H
49H
4AH
4BH
4CH
4DH
4EH
4FH
SOH
B-2

Create new program segment
Random block read
Random block write
Parse filename
Get date
Set date
Get time
Set time
Set/reset verify switch
Get disk transfer address
Get DOS 4.00 version number
Terminate process and remain resident
Reserved by DOS 4.00
Get/Set system value
Reserved by DOS 4.00
Get interrupt vector
Get disk free space
Reserved by DOS 4.00
Get/set country dependent information
Create subdirectory (MKDIR)
Remove subdirectory (RMDIR)
Change current directory (CHDIR)
Create a file (CREAT)
Open a file
Close a file handle
Read from a file or device
Write to a file or device
Delete a file from a specified directory (UNLINK)
Move file read/write pointer (LSEEK)
Change file mode (CHMOD)
110 control for devices (IOCtl)
Duplicate a file handle (DUP)
Force a duplicate of a file handle (FORCDUP)
Get current directory
Allocate memory
Free allocated memory
Modify allocated memory blocks (SETBLOCK)
Load or execute a program (EXEC)
Terminate a process (EXIT)
Get return code of a subprocess (WAIT)
Find first matching file (FIND FIRST)
Find next matching file (FIND NEXT)
Reserved by DOS 4.00

51H
52H
53H
54H
55H
56H
57H
58H
59H
5AH
5BH
5CH
5DH
5EOOH
5E02H
5E03H
5F02H
5F03H
5F04H
60H
61H
62H
63H
64H
65H
66H
67H
68H
69H
6AH
6BH
6CH

Reserved by DOS 4.00
Reserved by DOS 4.00
Reserved by DOS 4.00
Get verify setti ng
Reserved by DOS 4.00
Rename a file
Get/set a file's date and time
Reserved for DOS 4.00
Get extended error
Create unique file
Create new file
Lock/unlock file access
Reserved by DOS 4.00
Get machine name
Set printer setup
Get printer setup
Get redirection list entry
Redirect device
Cancel redirection
Reserved by DOS 4.00
Reserved by DOS 4.00
Get PSP address
Reserved by DOS 4.00
Reserved by DOS 4.00
Get extended country information
Get/set global code page
Set handle count
Commit file
Reserved by DOS 4.00
Reserved
Reserved by DOS 4.00
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 21 H.

B-3

• 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
(ODH-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
Definition

General
Registers

AX
AH
AL

Accumulator (16-bit)
Accumulator high-order byte (a-bit)
Accumulator low-order byte (a-bit)

8-4

General
Registers

BX
BH
BL

Base (16-bit)
Base high-order byte (8-bit)
Base low-order byte (8-bit)

CX
CH
CL

Count (16-bit)
Count high-order byte (8-bit)
Count low-order byte (8-bit)

OX
DH
DL

Data (16-bit)
Data high-order (8-bit)
Data low-order (8-bit)

Flags

OF,DF,IF,TF,SF,ZF,AF,PF,CF

Pointers

Stack pointer (16-bit)

Base pointer (16-bit)

Instruction pointer (16-bit)

Segment
Registers

Code segment (16-bit)

Data segment (16-bit)

Stack segment (16-bit)

Extra segment (16-bit)

8·5

Index
Registers

Destination index (16-bit)

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
Bit
Hex value

Low Byte

15 14 13 12 11 1098

76543210

8 4 2 1 8 4 21

84218421

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. FeB 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
B-6

codes. Programs can take advantage of extended error support both
from interrupt 24H critical error handlers and after issuing interrupt
21 H function calls. Do not code to specific error codes.

Extended Error Codes
Hexadecimal
Code
01H
02H
03H
04H
05H
06H
07H
08H
09H
OAH
OBH
OCH
OOH
OEH
OFH
10H
11H
12H
13H

Decimal
Code
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

14H
15H
16H
17H

20
21
22
23

18H
19H
1AH
1BH
1CH

24
25
26
27
28

Meaning
Invalid function number
File not found
Path not found
Too many open files (no handles left)
Access denied
Invalid handle
Memory control blocks destroyed
Insufficient memory
Invalid memory block address
Invalid environment
Invalid format
Invalid access code
Invalid data
Reserved
Invalid drive was specified
Attempt to remove the current directory
Not same device
No more files
Attempt to write on write-protected
diskette
Unknown unit
Drive not ready
Unknown command
Cyclic redundancy check (CRC) - part
of diskette is bad
Bad request structure length
Seek error
Unknown media type
Sector not found
Printer out of paper

B-7

Hexadecimal
Code
1DH
1EH
1FH
20H
21H
22H
23H
24H
25H
26H
27H-31H
50H
51H
52H
53H
54H
55H
56H
57H
58H
59H
5AH

Decimal
Code
29
30
31
32
33
34
35
36
37
38
39-49
80
81
82
83
84
85
86
87
88
89
90

Meaning
Write fault
Read fault
General failure
Sharing violation
Lock violation
Invalid disk change
FCB unavailable
Sharing buffer overflow
Reserved by DOS 4.00
Unable to complete file operation
Reserved by DOS 4.00
File exists
Reserved
Cannot make di rectory entry
Fail on INT 24
Too many redirections
Duplicate redirection
Inval id password
Invalid parameter
Network data fault
Function not supported by network
Required system component not
installed

Extended Error Codes
Hexadecimal
Code
32H
33H
34H
35H
36H
37H

B-8

Decimal
Code
50
51
52
53
54
55

Meaning
Network request not supported
Remote computer not listeningDuplicate name on network
Network path not found
Network busy
Network device no longer exists

Hexadecimal
Code
38H
39H
3AH
3BH
3CH
30H
3EH
3FH
40H
41H
42H
43H
44H
45H
46H
47H
48H
49H-4FH

Decimal
Code
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73-79

Meaning
NETBIOS command limit exceeded
System error; NETSIOS error
Incorrect response from network
Unexpected network error
Incompatible remote adapter
Print queue full
Not enough space for print file
Print file was cancelled
Network name was deleted
Access denied
Network device type incorrect
Network name not found
Network name limit exceeded
NETSIOS session limit exceeded
Sharing temporarily paused
Network request not accepted
Print or disk redirection is paused
Reserved

Error Classes
Hexadecimal
Value
01H

Decimal
Value
1

02H

03H
04H

3
4

05H

Description
Out of Resource: Example: out of space
or channels.
Temporary Situation: Something
expected to disappear with time. This is
not an error condition, but a temporary
situation such as a locked file.
Authorization: Permission problem.
Internal: Internal error in system software. Probable problem with system
software rather than a user or system
failure.
Hardware Failure: A serious problem
not the fault of user program.

B-9

Hexadecimal
Value
06H

Decimal
Value
6

07H

08H

09H

OAH
OBH

10
11

OCH

ODH

Description
System Failure: Serious failure of
system software not the fault of the
user, such as missing or incorrect configuration files.
Application Program Error: Inconsistent
requests.
Not Found: File or item not found.
Inconsistent requests.
Bad Format: File or value in invalid
format or type; unsuitable.
Locked: Locked file or item.
Media: Media failure such as incorrect
disk, CRC error, or defective media.
Already Exists: Duplication error, such
as declaring a machine name that
already exists.
Unknown: Classification does not exist
or is inappropriate.

Actions
Hexadecimal
Code
01H

Decimal
Code

02H

03H

B-10

Description
Retry: Retry a few times, then prompt
user to determine if the program should
continue or be terminated.
Delay Retry: Retry several times after
pause, then prompt user to determine if
the program should continue or be terminated.
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.

Hexadecimal
Code

04H

Decimal
Code
4

05H

06H
07H

Description
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.
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.
Ignore: Ignore.
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
Value

01H
02H
03H
04H
05H

Decimal
Value
1
2

3
4
5

Description
Unknown: Not specific; not appropriate.
Block Device: Related to random access
mass disk storage.
Net: Related to the network.
Serial Device: Related to serial devices.
Memory: Related to random access
memory.

8-11

OOH Program Terminate

Purpose
Stops the execution of a program.

Example
MOV
INT
: No return

AH.00H
21H

: Function Call - Terminate Program
: Issue request to DOS

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.

8-12

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
INT
MOV
CMP
JNE
MOV
INT
MOV
Normal_Char:

Character
Char
ExtChar

AH.elH
21H
Char.AL
AL.e
Normal_Char
AH.elH
21H
ExtChar.AL

;
;
;
;
;
;
;
;

LABEL
DB
DB

; Complete character
; Character buffer
; Character buffer

WORD
?
?

Function Call - keyboard input
Issue request to DOS
Save character
Extended character ?
No!
Function Call - keyboard input
Issue request to DOS
Save extended character

Comments
The character is checked for a Ctrl-Break. If Ctrl-Break is detected,
an interrupt 23H is executed.
For function call 01 H, extended ASCII codes require two function
calls. The first call returns OOH as an indicator that the next call will
return an extended code.

8-13

02H Display Output

Purpose
Outputs the character in DL to the standard output device.

Example
MOV
MOV

INT

CHAR

AH,02H
DL,Char
21H

; Function Call - Display Output
; Get character to display
; Issue request to DOS

; 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.

B-14

03H Auxiliary Input

Purpose
Waits for a character from the standard auxiliary device, then returns
that character in AL.

Example
MOV

AH.03H
21H
Char.AL

; Function Call - Auxiliary Input
: Issue request to DOS
: Save character

; Character buffer

MOV

INT

CHAR

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 10Cti.

B-15

04H Auxiliary Output

Purpose
Outputs the character in DL to the standard auxiliary device.

Example

CHAR

MOV

AH.a4H

; Function Call - Auxiliary Output

MOV

INT

DL.Char
21H

; Get character to output
; Issue request to DOS
; Nothing returned

; 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.

8-16

OSH Printer Output

Purpose
Outputs the character in DL to the standard printer device.

Example
MOV
MOV

INT

CHAR

AH.0SH
DL.Char
21H

:
:
:
:

Function Call - Printer Output
Get character to output
Issue request to DOS
Nothing returned

: Character buffer

8-17

06H Direct Console 1/0

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,e6H
MOV
DL,-l
INT
21H
JZ
In_loop
MOV
Char,AL
CMP
AL,e
JNE
Normal_Char
MOV
AH,e7H
INT
21H
MOV
ExtChar,AL
Normal_Char:

;
;
;
;
;
;
;
;
;
;

Function Call - Direct Console I/O
eFFH for input
Issue request to DOS
No character yet on input
Save character
Extended Character ?
No!
Function Call - Keyboard Input
Issue request to DOS
Save extended character

or
MOV
MOV
INT

AH,e6H
DL,Char
21H

Character
Char
ExtChar

; Function Call - Direct Console I/O
; Get character to display (not eFFH)
; Issue request to DOS

LABEL WORD; Complete character
DB
? ; Character buffer
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 OSH, extended ASCII codes require two function
calls. The first call returns OOH as an indicator that the next call will
return an extended code.

8-18

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.e7H
INT 21H
MOV Char.AL
CMP AL.e
JNE Normal_Char
MOV AH.e7H
INT 21H
MOV ExtChar.AL
Normal_Char:

Character
Char
ExtChar

LABEL
DB
DB

;
;
;
;
;
;
;
;

Function Call - Direct Console Input (no echo)
Issue request to DOS
Save character
Extended character ?
No!
Function Call - Direct Console Input (no echo)
Issue request to DOS
Save extended character

WORD
?

; Complete character
; Character buffer
; 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 OOH as an indicator that the next call will
return an extended code.

8-19

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.9SH
;
INT 21H
;
MOV Char.AL
;
CMP AL.9
;
JNE Normal_Char;
MOV AH.9SH
;
INT 21H
;
MOV ExtChar.AL;
Normal_Char:
Character
Char
ExtChar

Function Call - Console Input (no echo)
Issue request to DOS
Save character
Extended character?
No!
Function Call - Console Input (no echo)
Issue request to DOS
Save extended character

LABEL
DB
DB

WORD
?
?

; Complete character
; Character buffer
; 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 OOH as an indicator that the next call will
return an extended code.

8-20

09H Display String

Purpose
Sends the characters in the string to the standard output device.

Example
MOV
MOV
MOV
MOV
INT

AX,SEG String
DS,AX
:Set DS:DX to string
DX,OFFSET String
AH,09H
:Function Call - Display String
21H
:Issue request to DOS

String

DB
DB
DB

"Thi s string ends at the first Dollar"
0DH,0AH
11$11

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 OOH and OAH represent carriage return and line feed,
respectively.

8-21

OAH Buffered Keyboard Input

Purpose
Reads characters from the standard input device and places them in
the buffer beginning at the third byte.

Example
MOV
MOV
MOV
MOV

AX.SEG Buffer
OS.AX
OX.OFFSET Buffer
AH.0AH

INT 21H

Buffer
Curlen

DB 128
DB?

CurText DB

;Set OS:OX to return Buffer
;Function Call-Buffered
;Keyboard Input
;Issue request to DOS

;
;
;
128 DUpe?) ;

Max length of input
Number of characters input
(excludes Return (90H))
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 O. 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 (ODH),
which is always the last character.

B-22

OBH Check Standard Input Status

Purpose
Checks if there is a character available from the standard input
device.

Example
In_LOOP:
MOV
AH.0BH
INT
21H
CMP
AL.-l
JNE
In_LOOP:

; Function Call - Check Input
; Issue request to DOS
; eFFH indicates character available

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.

B-23

OCH 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.9CH

MOV

AL.Function

INT

21H

8·24

:
:
:
:
:
:

Function Call - Clear keyboard &
Invoke function
Function Call to execute
(only 91H. 96H. 97H. 9SH. and 9AH are allowed).
Issue request to DOS
Output depends on Function Call selected

ODH Disk Reset

Purpose
Writes to the disk file buffers that have been modified. All buffers are
then made available for reuse.

Example
MOV

INT

AH.0DH
21H

; Function Call - Disk Reset
; Issue request to DOS
: No return

Comments
It is necessary to close or commit all open files to correctly update
the disk directory.

B·25

OEH Select Disk

Purpose
Selects the drive specified in DL (O=A, 1 = B, etc.) (if valid) as the
default drive.

Example
MOV
MOV
INT
MOV
MOV
INT
CMP
JNE

AH.0EH
DL.Drive
21H
LastDrive.AL
AH.19H
21H
AL.DL
Error

Drive
LastDrive

DB
DB

;
;
;
:
;
;
;
;

Function Call - Select Disk
Drive to select
(0=A:. l=B: •.•• )
Issue request to DOS
Save max drive number (l=A:. 2=B: •.•. )
Function Call - Get Current Disk
Issue request to DOS
Selected drive = requested
No. Error!

; New Drive to select
; 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.

B·26

OFH 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 OOH and the
FCB is filled as described below.

Example
MOV
MOV
MOV
MOV
INT

AX.SEG FCB
;Address FCB Parameter Block
DS.AX
DX.OFFSET FCB
AH.0FH
;Function Call-FCB Open
21H
;Issue request to DOS

FeB
Drive
FName
Ext

LABEL
DB
DB
DB
DB

BYTE
0
IIFILENAMEII
IIEXm
25 DUP(0)

;
;
;
;

Drive (0=Current. l=A. 2=B •.•• )
File Name
(blank padded)
File Extension (blank padded)
Filled in by DOS 4.00

Comments
AL is OOH 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 O. 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

B·27

OFH Open File
record size (FeB 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 30H.

8-28

10H Close File

Purpose
Closes a file.

Example
MOV
MOV
MOV
MOV
INT
CMP
JNE

AX,SEG FCB
OS,AX
OX,OFFSET FCB
AH,laH
21H
AL,a
Error

; Address FCB Parameter Block
;
;
;
;

Function Call-FCB Close
Issue request to DOS
File Closed?
No, Error!

FCB
LABEL BYTE
; Contents set by previous operations

Comments
AL is OOH if the file is closed.
AL is FFH if the fi Ie 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 OOH.

B-29

11H Search for First Entry

Purpose
Searches the current directory for the first matching filename.

Example
MOV
MOV
MOV
MOV
INT
MOV
MOV
MOV
MOV
INT
CMP
JNE

AX.SEG DTA
DS.AX
DX.OFFSET DTA
AH.1AH
21H
AX.SEG FeB
DS.AX
DX.OFFSET FCB
AH.llH
21H
AL.e
Error

; Address Buffer for found file
; information
; Function Call-Set DTA address
; Issue request to DOS
; Address FCB parameter block
;
;
;
;

Function Call-FeB search first
Issue request to DOS
File found?
No. Error!

FeB
Fdrive
Fname
Fext

LABEL
DB
DB
DB
DB

BYTE
0
"FILENAME"
"EXm
25 DUP(0)

;
;
;
;

Drive (0=Current. l=A. 2=B •••• )
File name
(blank padded. may use ?)
File extension (blank padded. may use ?)
Filled in by DOS

DTA
Ddrive
Dname
Dext

LABEL
DB
DB
DB
DB

BYTE
?
????????
???
25 DUP(0)

;
;
;
;

Drive
File Name
(blank padded)
File Extension (blank padded)
Filled in by DOS 4.00

II
II

Comments
AL is OOH 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
8-30

11H Search for First Entry
found, AL returns OOH and the locations at the disk transfer address
are set as follows:
• If the FeB provided for searching was an extended FeB, 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 FeB, 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 FeB with the same search attributes as the search FeB.
• If the FeB provided for searching was a standard FeB, 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 FeB.
Notes:

If an extended FeB 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.

8·31

12H Search for Next Entry

Purpose
Searches the current directory for the next matching filename.

Example
MOV
MOV
MOV
MOV
INT
MOV
MOV
MOV
MOV
INT
CMP
JNE

AX.SEG DTA
DS.AX
DX.OFFSET OTA
AH.IAH
21H
AX.SEG FCB
DS.AX
DX.OFFSET FCB
AH.12H
21H
AL.a
Error

; Address Buffer for found file
; Information
; Function Call-Set DTA address
; Issue request to DOS
; Address FCB Parameter Block
;
;
;
;

Function Call-FCB Search Next
Issue request to DOS
File found?
No. Error I

FCB
LABEL BYTE
; As set by FCB Search First
DTA
Drive
Fname
Ext

LABEL
DB
DB
DB
DB

BYTE
?

"????????"
II ??? II
25 DUP(B)

;
;
;
;

Drive
File Name
(blank padded)
File Extension (blank padded)
Filled in by DOS 4.BB

Comments
AL is OOH 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.

8·32

12H Search for Next Entry
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.

B-33

13H Delete File

Purpose
Deletes all current directory entries that match the specified
filename. The specified filename cannot be read-only.

Example
MOV
MOV
MOV
MOV
INT
CMP
JNE

AX.SEG FCB
DS.AX
DX.OFFSET FCB
AH.13H
21H
AL.e
Error

FCB
Drive
FName
Ext

LABEL
DB
DB
DB
DB

;Address FCB Parameter Block
;Function Call-FCB Delete File
;Issue request to DOS
;File(s) Deleted?
;No. Error!

BYTE

Filename
Ext
25 DUP(e)

;
;
;
;

Drive
File Name
(blank padded. may use ?)
File Extension (blank padded. may use ?)
Filled in by DOS

Comments
AL is OOH 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 OOH.
If the file is specified in read-only mode, the file is not deleted.
Nole: Close open files before deleting them.
Network Access Rights: Requires Create access rights.

8·34

14H Sequential Read

Purpose
Loads the record addressed by the current block (FCB bytes C-O) and
the current record (FCB byte 1F) at the disk transfer address (OTA),
then the record address is increased.

Example
MOV
MOV
MOV
MOV
INT
MOV
MOV
MOV
MOV
INT
CMP
JNE

AX.SEG DTA
DS.AX
DX.OFFSET DTA
AH,lAH
21H
AX,SEG FCB
DS,AX
DX,OFFSET FCB
AH,14H
21H
AL,e
Error

;Address Data buffer
;Function call Set OTA Address
;Issue request to DOS
;Address FCB Parameter Block
;Function Call-FCB Sequential Read
;Issue request to DOS
;Data Read?
;No, Error!

FCB
LABEL BYTE
; Set by previous open
OTA
LABEL BYTE
DB
?Dup(e)

;1/0 buffer

Comments
AL is OOH 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 OTA was too small (the read was not completed).
AL is 03H if EOF (a partial record was read and filled out with O'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.

B-35

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
MOV
MOV
MOV
INT
MOV
MOV
MOV
MOV
INT
CMP
JNE

AX.SEG OTA
OS.AX
OX.OFFSET OTA
AH.IAH
21H
AX.SEG FCB
OS.AX
OX.OFFSET FCB
AH.1SH
21H
AL.e
Error

FCB
LABEL BYTE
; Set by previous open
OTA
LABEL BYTE
DB
?Dup(e)

;Address Data buffer
;Function Set DTA Address
;Issue request to DOS
;Address FCB Parameter Block
;Function Call-FCB Sequential Write
;Issue request to DOS
;Data Written?
;No. Error!

;1/0 buffer

Comments
AL is OOH if the write was successful.
AL is 01 H 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 01 H is returned in AL.
Network Access Rights: Requires Write access rights.

B-36

16H Create File

Purpose
Creates a new file.

Example
MOV
MOV
MOV
MOV
INT
CMP
JNE

AX,SEG FCB
DS,AX
DX,OFFSET FCB
AH,16H
21H
AL,e
Error

FCB
Fdrive
Fname
Fext

;Address FCB parameter block
;Function Call-FCB create file
;Issue request to DOS
;File created and opened?
;No, Error!

LABEL
DB
DB
DB
DB

BYTE
e
"FILENAME"
EXT"
25 DUP(e)
II

;
;
;
;

Drive (e=Current, l=A, 2=B, ... )
File name
(blank padded)
File extension (blank padded)
Filled in by DOS

Comments
AL is OOH 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 O-Iength file, the file is opened (see function
call OFH), and AL returns OOH.
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.

8-37

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
MOV
MOV
MOV
INT
CMP
JNE

AX.SEG FCB
DS.AX
DX.OFFSET FCB
AH.17H
21H
AL.e
Error

FCB
Fdrive
Fname
Fext

LABEL
DB
DB
DB
DB
NewName DB
NewExt DB
DB

;Address FCB Parameter Block
;Function Call-FCB Rename File
;Issue request to DOS
;File(s) Renamed?
;No. Error!

BYTE

II FILENAME"
IIEXP
5 DUP(e)
II FILENAME"
IIEXP
7 DUP(e)

;
;
;
;
;
;
;

Drive (0=Current. l=A. 2=B •••• )
File Name
(blank padded.
File Extension
(blank padded.
Reserved
New Fil e Name
(blank padded.
New File Extension (blank padded.
Reserved

may use ?)
may use ?)
may use ?)
may use ?)

Comments
AL is OOH if the file or files were renamed.
AL is FFH if a file in the current directory did not match or the new
name al ready exists.
Use Function Call 59H (Get Extended Error) to determine the actual
error condition.

8-38

17H Rename File
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 + 11 H) 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.

8-39

19H Current Disk

Purpose
Determines the current default drive.

Example
MOV
INT
MOV
Disk

AH.19H; Function Call - Get Current Disk
21H
; Issue request to DOS
Disk.AL; Save Current Disk
?

; Current Disk code (0=A:. 1=B: •... )

Comments
AL returns with the code of the current default drive (0 = A, 1 = B, and
others.).

B-40

1AH Set Disk Transfer Address

Purpose
Sets the disk transfer address to DS:DX.

Example
MOV
MOV
MOV
MOV
INT

OTA

AX.SEG OTA
OS.AX
OX.OFFSET OTA
AH.1AH
21H

LABEL

BYTE

;Address Buffer
;Function Call-Set OTA address
;Issue request to DOS

; Oata Buffer

Comments
The area defined by this call is from the address in DS:DX to the end
of the segment in OS. 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.

B-41

1BH Allocation Table Information

Purpose
Returns information about the allocation table for the default drive.

Example
MOV AH,lBH
INT
MOV
MOV
MOV
MOV
MOV

;
;
21H
;
NumAllocUnits,DX
;
NumSectsAllocUnit,AL
;
SectSize,CX
;
WORD PTR MediaType@+0,BX;
WORD PTR MediaType@+2,DS

NumAllocUnits
NumSectsAllocUnit
SectSize
MediaType@

DW
DB
DW
DD

?
?
?
?

Function Call - Allocation Table
Information
Issue request to DOS
Save Number of Allocation Units
Save Number of Sectors/Allocation Unit
Save of Sector Size
Save Pointer to Media Type Byte

;
;
;
;

Number of Allocation Units on Current Drive
Number Sectors in an Allocation Unit
Sector Size
Pointer to Media Type byte

Comments
Refer to function call 36H (Get Disk Free Space).

B-42

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
; Drive requested (0=current.

MOV

DL.Drive

INT
MOV
MOV
MOV
MOV
MOV

21H
NumAllocUnits.DX
NumSectsAllocUnit.AL
SectSize.CX
WORD PTR MediaType@+0.BX
WORD PTR MediaType@+2.DS

: l=A: . . . . )

Drive
NumAllocUnits

DB
OW

NumSectsAllocUnit DB
SectSize
MediaType@

OW
DO

?
?

:
;
;
:
;

Issue request to DOS
Save Number of Allocation Units
Save Number of Sectors/Allocation Unit
Save of Sector Size
Save Pointer to Media Type Byte

;
:
:
:
;
;
;

drive number to get info for
Number of Allocation Units
on specified drive
Number Sectors in an
Allocation Unit
Sector Size
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).

8-43

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
MOV
MOV
MOV
MOV
INT
MOV
MOV
MOV
MOV
INT
CMP
JNE

AX.SEG DTA
OS.AX
OX.OFFSET OTA
AH.IAH
21H
AX.SEG FCB
OS.AX
OX.OFFSET FCB
AH.21H
21H
AL.e
Error

;Set up FCB
;Address Oata buffer
;Function Set DTA Address
;Issue request to DOS
;Address FCB Parameter Block
;Function Call-FCB Random Read
;Issue request to DOS
;Oata Read?
;No. Error!

FCB
LABEL BYTE
; Set by previous open
; OTA label byte

Comments
AL is OOH if the read was successful.
AL is 01 H 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 O'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

8-44

21H Random 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.

8-45

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
MOV
MOV
MOV

AX.SEG FCB
DS.AX
DX.OFFSET FCB
AH.24H

INT
MOV
MOV
MOV
MOV
INT
MOV
MOV
MOV
MOV
INT
CMP
JNE

21H
AX.SEG DTA
DS.AX
DX.OFFSET DTA
AH.IAH
21H
AX.SEG FCB
DS.AX
DX.OFFSET FCB
AH.22H
21H
AL.a

Error

:Address FCB parameter block
:Function Call-FCB Set
:Relative record field
:Issue request to DOS
:Address data buffer
:Function Set DTA address
:Issue request to DOS
:Address FCB parameter block
:Function Call-FCB random writers
:Issue request to DOS
:Data written?
:No. error!

FCB
LABEL BYTE
: Set by previous open
DTA
LABEL BYTE

Comments
AL is OOH 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.
8-46

22H Random Write
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.

B-47

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
MOV
MOV
MOV
INT
CMP
JNE

AX.SEG FCB
DS.AX
DX.OFFSET FCB
AH.23H
21H
AL.0
Error

FCB
Drive
Name
Ext

LABEL
DB
DB
DB
DB

; Address FCB parameter block
;
;
;
;

Function Call-FCB file size
Issue request to DOS
File found?
No. error!

BYTE
0
"FILENAMP
"EXT"
25 DUP(0)

;
;
;
;

Drive (0=Current. l=A. 2=B ••.. )
File name
(blank padded)
File extension (blank padded)
Filled in by DOS

Comments
AL is OOH 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.

8-48

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
MOV
MOV
MOV

AX.SEG FCB
:Address FCB parameter block
DS.AX
DX.OFFSET FCB
AH.24H
:Function Call-FCB set
:Relative record field
:Issue request to DOS
INT 21H

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.

8-49

25H Set Interrupt Vector

Purpose
Sets the interrupt vector table for the interrupt number.

Example
MOV
MOV
MOV
MOV

AX.SEG Handler
;Address new handler
OS.AX
OX.OFFSET Handler
AH.25H
;Function Call - Set Interrupt
;Vector
MOV AL.Vector
INT 21H
;Issue request to DOS

Vector
Handler:

;Number of vector to be replaced
;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.

B-SO

26H -

Create New Program Segment

Purpose
Creates a new program segment.

Example
MOV

AH.26H

MOV
INT

DX.SEG PSP
2lH

PSP

LABEL
DB

;
;
;
;

Function Call - Create Program
Segment
Segment address to create new PSP
Issue request to DOS

BYTE
; Area to fill in
laaH DUP(e)

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 OAH. 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.

B-51

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
MOV
MOV
MOV
1NT

AX.SEG OTA
OS.AX
OX.OFFSET OTA
AH.1AH
21H

:Address data buffer

MOV
MOV
MOV
MOV

AX.SEG FCB
OS.AX
OX.OFFSET FCB
AH.24H

:Address FCB parameter block

1NT
MOV
MOV
MOV
MOV
MOV
1NT
CMP
JNE

21H
AX.SEG FCB
OS.AX
OX.OFFSET FCB
CX.Records_to_read
AH.27H
21H
AL.0
Error

:Function set OTA address
:1ssue request to DOS

:Function Call - FCB Set
:Relative Record Field
:1ssue request to DOS
:Address FCB parameter block
:number of records to read
:Function Call - FCB random block read
:1ssue request to DOS
:Oata read?
:No. error!

FCB
LABEL BYTE
: Set by previous open
OTA
LABEL BYTE
OB
?Oup(0)
Records_to_read OW
?

:1/0 buffer

27H Random Block Read
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.

8-53

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
MOV
MOV
MOV
MOV
INT

AX.SEG DTA
DS.AX
DX.OFFSET DTA
AH.IAH
21H

MOV
MOV
MOV
MOV

AX.SEG FCB
OS .. AX
DX.OFFSET FeB
AH.24H

;Set up disk transfer address
;Address data buffer
;Function set DTA address
;Issue request to DOS
;Address FeB parameter block
;Function Call-FCB set
;Reiative record field
;Issue request to DOS

INT 21H
MOV
MOV
MOV
MOV
MOV
INT
CMP
JNE

DTA

AX.SEG FCB
DS.AX
DX.OFFSET FCB
CX. Records_to_wri te
AH.28H
21H
AL.e
Error

LABEL

BYTE

?DUP(e)

;Address FeB parameter block
;Number of records to write
;Function Call - FCB Random Block write
;Issue request to DOS
;Data written?
;No. error!

I/O Buffer

8-54

28H Random Block Write
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.

8·55

29H Parse Filename

Purpose
Parses the specified filename.

Example
MOV
MOV
MOV
MOV
MOV
MOV
MOV
MOV
INT

AX.SEG CmdBuf
OS.AX
SI.OFFSET CmdBuf
AX.SEG FCB
ES.AX
OI.OFFSET FCB
AH.29H
AL.OPTIONS
21H

;Function Call - FCB Parse Filename
;Set desired action
;Issue request to DOS

CMP
JE

AL.-l
Error

;Orive valid?
;No. Error!

CmdBuf

LABEL
DB

;Address command string
;Address FCB Parameter Block

BYTE
" a:file.ext

lI.aOH

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:

bit:

7
6
5
4

If bit 0 = 1, leading separators are scanned off the command line at
OS:SI. Otherwise, no scan-off of leading separators takes place.
If bit 1 = 1, the drive 10 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.

B-56

29H Parse 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 ,<, >,
ters.

I, I,

", [, ], and any control charac-

Output:
AL is OOH 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.

8-57

2AH Get Date

Purpose
Returns the day of the week, the year, month and date.

Example
MOV
INT
MOV
MOV
MOV
MOV

DayofWeek
Year
Month
Day

AH,2AH
21H
DayofWeek,AL
Year,CX
Month,DH
Day,DL

;
;
;
;
;
;

DB
OW
DB
DB

; 9=Sunday, ••• 6=Saturday
; 1989 to 2999
; 1 to 12
; 1 to 31

?
?
?
?

Function Call - Get Date
Issue request to DOS
Save Day of the Week
Save Year
Save Month
Save Day

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.

I-58

2BH Set Date

Purpose
Sets the date (also sets CMOS clock, if present).

Example
MOV
MOV
MOV
MOV
INT
CMP
JNE
Year
Month
Day

AH.2BH
CX.Year
DH.Month
DL.Day
21H
AL.0
Error
OW
DB
DB

:
:
:
:
:
:
:
?
?
?

Function Call - Set Date
Set 'tiar
Set Month
Set Day
Issue request to DOS
Valid Date?
No!

: 1980 to 2099
: 1 to 12
: 1 to 31

Comments
AL is OOH 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 OOH if the date is valid and the set operation is
successful. AL returns FFH if the date is not valid.

B-59

2CH Get Time

Purpose
Returns the time; hours, minutes, seconds and hundredths of
seconds.

Example
MOV

AH,2CH

INT
MOV
MOV
MOV
MOV

Hour
Minute
Second
Hundredth

21H
Hour,CH
Minute,CL
Second,DH
Hundredth,DL

:
:
:
:
;
:
:

Function Call Get Time
Issue request to DOS
Save Hour
Save Minute
Save Second
Save Partial Second

DB
DB
DB
DB

:
:
:
:

e to
e to
e to
e to

?
?
?
?

23
59
59
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
CL
DH
DL

Hours (0 - 23)
Minutes (0-59)
Seconds (0 - 59)
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.

8-60

2DH Set Time

Purpose
Sets the time (also sets the CMOS clock, if present).

Example
MOV
MOV
MOV
MOV
MOV
INT
CMP
JNE

Hour
Minute
Second
Hundredth

AH.2DH
CH.Hour
CL.Minute
DH.Second
DL.Hundredth
21H
AL.a

Error

DB
DB
DB
DB

?
?
?
?

;
;
;
;
;
;
;
;

Function Call - Set Time
Sst Hour
Set Minute
Set Second
Set Partial Second
Issue request to DOS
Valid Time?
No!

;
;
;
;

a to
a to
a to
a to

23
59
59
99

Comments
AL is OOH 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
retu rns OOH.
If your system has a CMOS realtime clock, it will be set.

8-61

2EH Set/Reset Verify Switch

Purpose
Sets the verify switch.

Example
; To set VERIFY=OFF
MOV

AH.2EH

MOV
INT

AL.e
21H

;
;
;
;

Function Call - Set
VERIFY
Set OFF
Issue request to DOS

;
;
;
;

Function Call - Set
VERIFY
Set ON
Issue request to DOS

; To set VERIFY=ON
MOV

AH.2EH

MOV
INT

AL,l
21H

Comments
On entry, AL must contain 01H to turn verify on, or OOH 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.

B-82

2FH Get Disk Transfer Address (DTA)

Purpose
Returns the current disk transfer address.

Example
MOV
INT
MOV
MOV

DTA@

AH.2FH

;
;
21H
;
WORD PTR DTA@+G.BX ;
WORD PTR DTA@+2.ES

Function Call - Get
DTA Address
Issue request to DOS
Save Address

; DTA Buffer

Comments
On entry, AH contains 2FH. On return, ES:BX contains the current
Disk Transfer Address. You can set the OTA using function call1AH.

B-83

30H Get DOS Version Number

Purpose
Returns the DOS version number.

Example
PUSH
PUSH
MOV
INT
MOV
MOV
POP
POP

ex
BX
AH.3aH

; ex and BX destroyed in call

:
:
21H
:
MajorVersion.AL :
MinorVersion.AH
BX
ex

MajorVersion DB
MinorVersion DB

?
?

Function eall - Get DOS 4.aa
Version
Issue request to DOS
Save Version

: X of X.YY
: YY of X.YY

Comments
On entry, AH contains 30H. On return, ex and ex are set to O. 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.

8-84

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

MOV
MOV
INT
INT

AL.RetCode
DX.MySize
21H

:
:
:
:
:
:

DB
OW

: Value to return to my EXEC'er
: Size of my code and data
: (in paragraphs)

RetCode
MySize

2eH

?
?

Function Call - Terminate
and Keep Process
Set value of ERRORLEVEL
Set my program and data size
Issue request to DOS
Be safe if on DOS 4.ee Version 1.X

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.

8-85

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

MOV
INT
MOV

AL.0
21H
BREAK.DL

;
:
:
:
:

Function Call - Get/Set
System value
Do Get BREAK
Issue request to DOS
Save state

:
:
:
:
:

Function Call - Get/Set
System value
Do Set BREAK
Set OFF
Issue request to DOS

:
:
:
:
:

Function Call - Get/Set
System Value
Do Set BREAK
Set ON
Issue request to DOS

:
:
:
:
:

Function Call - Get/Set
System Value
Do Get Boot Drive
Issue request to DOS
Save boot drive

: To set BREAK=OFF
MOV

AH.33H

MOV
MOV
INT

AL.l
DL.0
21H

: To set BREAK=ON
MOV

AH.33H

MOV
MOV
INT

AL.l
DL.l
21H

: To get the Boot Drive

BREAK
Drive

B-86

MOV

AH.33H

MOV
INT
MOV

AL.5
21H
Drive.DL

DB
DB

: Current BREAK state (0=OFF. l=ON)
; DOS 4.00 boot drive

33H Get/Set System Value
Comments
For BREAK:
AL contains OOH to request the current state of Ctrl-Break checking.
On return DL contains the current state (OOH = OFF, 01H = ON).
AL contains 01H to set the state. DL contains the new state (OOH =
OFF, 01H = ON).
For boot drive:
AL contains 05H to request the boot drive. On return DL contains the
drive (A: = 1, C: = 3, ... ).

8-67

3SH Get Interrupt Vector

Purpose
To obtain the address in an interrupt vector.

Example
MOV

AH,35H

MOV
INT
MOV
MOV

AL,Vector
21H
WORD PTR OldVect+9,BX
WORD PTR OldVect+2,ES

OldVect
Vector

DO
DB

?
?

;
;
;
;

Function Call
Set Interrupt
Vector to get
Issue request

Vector
(9 to 255)
to DOS

; Previous vector contents
; 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.

B·68

36H Get Disk Free Space

Purpose
Returns the disk free space (available clusters, clusters/drive,
bytes/sector) .

Example
MOV

AH.36H

MOV

DL.Drive

INT
CMP
JE
MOV

21H
AX.-l
Error
SectAU.AX

MOV

AvailAU.BX

MOV
MOV

SectSize.CX
TotalAU.DX

MOV

AX.SectSize

MUL
MOV
MOV
MUL
MOV
MOV
MOV
MUL
MOV
MOV

SectAU
CX.AX
AX. Total AU
CX
WORD PTR TotalBytes+0.AX
WORD PTR TotalBytes+2.DX
AX. Avail AU
CX
WORD PTR FreeBytes+0.AX
WORD PTR FreeBytes+2.DX

SectAU

Avail AU
SectSize
Total AU

OW
OW
OW

?
?
?

Total Bytes
FreeBytes
Drive

DO
DO
DO

?
?
?

Funct i on Ca 11 Get disk free space
Drive to query
(0=current. l=A:.
2=B: •.•. )
Issue request to DOS
Error?
Yes
Save allocation unit
Size
Save free allocation
Units
Save sector size
Save disk size
Calculate allocation
Unit size
CX = bytes/AU
Calculate total space
Save it
Calculate free space
Save it

: Sectors in an
: Allocation unit
Free allocation units
Bytes in a sector
Number of allocation
Units on DL disk
Disk size in bytes
Free space in bytes
Drive number to get info for

B-69

36H Get Disk Free Space
Comments
If the drive number in DL was valid, ex contains the number of available allocation units, OX contains the total number of allocation units
on the drive, ex contains the number of bytes per sector, and AX contains the number of sectors for each allocation unit.

B-70

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

MOV
MOV
MOV
INT
JC

AL.CountryID
BX. Count ry lOX
DX.-l
21H
Error

:
;
:
:

Function Call - Get/Set
Country Information
Country ID (-1 if >= 255)
Country ID (if AL--l)
Indicate set country code
Issue request to DOS
Error code in AX

: To get Country Information
MOV
MOV
MOV
MOV
MOV
MOV

AX.SEG Buffer
DS.AX
DX.OFFSET Buffer
AH.38H
; Country ID (-1 if >= 255)
AL.CountrylO
: (0 to get current country)
BX. Count ry lOX : Country ID (if AL=-l)

INT
JC
MOV

: Issue request to DOS
21H
Error
: Error code in AX
CountryCode.BX : Save current Country Code

CountryCode

Current country code

CountryIDX

Extended country code for input

Buffer
Country I0

LABEL
DB

WORD
?

Country information (see format below)
: Country code for input

8·71

38H Get or Set Country Dependent Information
Country Information

DateFormat

$Symbol

Sep1999

"?",9

Sepl

"?",9

SepDate

"?",9

SepTime

"?",9

$Format

SigDigits
TimeFormat

DB
DB

?
?

UpperCaseAL@ DO

SepData

"?",9

Reserved

5 DUP(?)

8-72

???? II ,9

Date Format:
9 = m d y order
1 = d my order
2 = y m d order
Currency Symbol
exampl e: II OM II ,e,?, 7
Thousands Separator
example: ",II,a
Fractions Separator
example: 11.II,a
Date Separator
exampl e: "/" ,a
Time Separator
example: ":",a
Currency Format:
9 = currency symbol, value
1 = value, currency symbol
2 = currency symbol, space, value
3 = value, space, currency symbol
4 = currency symbol is decimal separator
Number of Significant Digits in Currency
Time Format:
9 = 12 hour clock
1 = 24 hour clock
Address of Routine to Upper Case AL
Only for values >=S9H
Data List Separator
example: ",II,a
Reserved for future

38H Get or Set Country Dependent Information
Comments
The date format has the following values and meaning:

Code
O=USA
1 = Europe
2=Japan

Date
m dy
d my
ymd

Case Map Call Address: The register contents for the case map call
are:

On
Entry

ASCII code of character to be converted to uppercase

On
Return

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.

8-73

39H Create Subdirectory (MKDIR)

Purpose
Creates the specified directory.

Example
MOV
MOV
MOV
MOV
INT
JC

AX.SEG
DName ;Directory Name
DS.AX
DX.OFFSET DName
AH.39H
;Function-Make a directory
21H
;Issue request to DOS
Error

DName

"?? .. ??".e ; ASCIIZ Name
; Example:
; "c:\dir".e

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.

8-74

3AH Remove Subdirectory (RMDIR)

Purpose
Removes the specified directory.

Example
MOV
MOV
MOV
MOV
INT
JC

AX.SEG DName
DS.AX
DX.OFFSET DName
AH.3AH
21H
Error

DName

;Directory name
;Function-Remove directory
;Issue request to DOS

"?? •• ??".0 ; ASCIIZ Name
example: Ic:\dir".0

Comments
On entry, DS:DX contains the address of an ASCIIZ string with the
drive and di rectory path names. The specified di rectory 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.

8·75

3BH Change the Current Directory (CHOIR)

Purpose
Changes the current directory to the specified directory.

Example
MOV
MOV
MOV
MOV
INT
JC

AX,SEG OName
OS,AX
OX,OFFSET OName
AH,3BH
21H
Error

OName

;Oirectory name
;Function - Change directory
;Issue request to DOS

"?? .• 17",0

; ASCIIZ Name
example: Ic:\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.

8-76

3CH Create a File (CREAl)

Purpose
Creates a new file or shortens an old file to 0 length in preparation for
writing.

Example
MOV
MOV
MOV
MOV
MOV

AX,SEG FName
OS,AX
OX,OFFSET FName
AH,3CH
CX,Attribute

INT
JC
MOV

21H
Error
Handle,AX

FName

Handle
Attribute

OW
OW

;File name
;Function - Create a File
; Attribute of the file
; Allowed values
0001H=Read only
; 0002H=Hidden
; 0004H=System
; 0008H=Volume label
; Issue request to DOS
; Error code in AX
; Save file handle for

"?? •• ??",0 ; ASCIIZ Name
; example: Ic:\dir\file.ext",0
7
; File handle
7
; 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.

8·77

3DH Open a File

Purpose
Opens the specified file.

Example
MOV
MOV
MOV
MOV
MOV
INT
JC
MOV

AX,SEG FName
OS,AX
OX,OFFSET FName
AH,30H
AL,OpenMode
21H
Error
Handle,AX

: File name
; Function - Open a File
; Issue request to DOS
; Error code in AX
; Save file handle for following operations

FName

"?? .• ??" ,0

Handle
OpenMode

OW
DB

?
?

; ASCIIZ Name
; example: "c:\dir\file.ext",e
; File Handle
: 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.
8·78

3DH Open a File
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
Sharing mode field
Reserved field
Access field

Specifies if the opened file is inherited by a
subordinate process.
Defines which operations other processes can
perform on the file.
Defines which operations the current process
can perform on the file.

Bit Fields
The bit fields are mapped as follows:
< S > < A >

Open Mode bits

7 654 3 21

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)
B-79

3DH Open a File
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).

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

B-80

3DH -

Open a File
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 shari ng modes and an attem pt 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.

File Opened By

Read-Only
Access

Sharing Mode

FCB

Read-Only

DenyWrite

Handle Read

Read-Only

DenyWrite

Handle Write

Error

Handle
Read/Write

Error

---------

B-81

3DH Open a File

File Opened By

Nol Read-Only
Access

Sharing Mode

FCB

Read/Write

Compati bi Iity

Handle Read

Read

Compatibility

Handle Write

Write

Compatibility

Handle
Read/Write

Read/Write

Com pati bility

DenyRead/Wrlle 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.
DenyWrlle 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.

8-82

3DH Open a File
DenyRead Mode

A file successfully opened in OenyRead 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 OenyNone 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 shari ng modes:

B-83

3DH Open a File

DRW

R
W

D
W

A
L
L

Y
N
ORW
OW
DR
ALL
1

B-84

ALL

:2nd.3rd ••.. open is allowed
:2nd.3rd ••.. open is denied
:OenyRead/Write Mode (Exclusive)
: OenyWri te Mode
: OenyRead Mode
:Read/Write Mode
:Read Only Access
:Write Only Access
: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
JC

21H

Handle

: Issue request to DOS
: Error code in AX

Error

: 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 Extende'
Error) for additional information about the error class, suggested
action, and location.

B-85

3FH Read from a File or Device

Purpose
Transfers the specified number of bytes from a file into a buffer
location.

Example
MOV
MOV
MOV
MOV
MOV
MOV
INT
JC
CMP
JE
MOV

AX.SEG Buffer
DS.AX
DX.OFFSET Buffer
AH.3FH
BX.Handle
CX.BufSize
21H
Error
AX.e
EOF
SizeRead.AX

Handle
BufSize
Buffer
SizeRead

EQU
OW
OW
DB
OW

: Address data buffer
: Function - Read from a file

512
?
N

N DUP(?}
?

:
;
:
:
:
:

Buffer size
Issue request to DOS
Error code in AX
At End Of File?
Yes!
Save Amount Read

:
:
:
;
;

Typical buffer size
File Handle (from Open /Create)
Buffer Size. N is
Data Buffer
Amount of Data in Buffer

Comments
On entry, ex 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.
8-86

40H Write to a File or Device

Purpose
Transfers the specified number of bytes from a buffer into a specified
file.

Example
MOV
MOV
MOV
MOV
MOV
MOV
MOV
INT
JC
CMP
JB

AX,SEG Buffer
DS,AX
DX,OFFSET Buffer
CX,BufSize
AH,40H
BX,Handle
DX,OFFSET Buffer
21H
Error
AX,CX
FullDisk

Handle
BufSize
Buffer

;Data Buffer

;Function-Write to a File
;
;
;
;

Issue request to DOS
Error code in AX
Disk Full?
Yes!

EQU
512
DW?
DW
N
DB
N DUP(?)

;
;
;
;

Typical buffer size
File Handle (from Open / Create)
Buffer Size
Data Buffer

Comments
On entry, ax contains the file handle. ex contains the number of
bytes to write. DS:DX contains the address of the data to write.
This function call attempts to transfer (eX) 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
eX), 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 redi rected.
To truncate a file at the current position of the file pointer, set the
number of bytes (eX) 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.)

8·87

40H Write to a File or Device
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.

8-88

41H Delete a File from a Specified Directory (UNLINK)

Purpose
Removes a directory entry associated with a filename.

Example
MOV
MOV
MOV
MOV
INT
JC

FName

AX.SEG FName
DS.AX
DX.OFFSET FName
AH.41H
21H
Error

; File Name
; Function-Delete a File
; Issue request to DOS
; Error code in AX

"??. ??".9 : ASCIIZ Name
example: c:\dir\File.ext".9
I

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.

8-89

42H Move File Read Write Pointer (LSEEK)

Purpose
Moves the read/write pointer according to the method specified.

Example
MOV
MOV

MOV
MOV
MOV

INT
JC
MOV
MOV

AH.42H

; Function Call ; Move Read/Write Pointer
AL.Method
; Method of Positioning:
o = From Beginning of File
(BOF)
1 = From Current Position
; 2 = From End of File (EOF)
BX.Handle
; Select File
DX.WORD PTR Position+0 ; New Position = Position + METHOD
CX.WORD PTR Position+2
21H
; Issue request to DOS
Error
; Error code in AX
WORD PTR Position+0.AX ; Set new File Position
WORD PTR Position+2.DX

Handle

Position

Method

;
;
;
;

File Handle (from Open /
Create)
File Offset (may be
negative)

Comments
On entry, AL contains a method value. BX contains the file handle.
CX:OX contains the desired offset in bytes with ex containing the
most significant part. On return, OX:AX contains the new location of
the pointer with OX 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.

8·90

42H -

Move File Read Write Pointer (LSEEK)
This function call moves the read/write pointer according to the following methods:

Description

The pOinter is moved CX:DX bytes (offset) from the
beginning of the file.

The pointer is moved to the current location plus
offset.

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.

8·91

43H Change File Mode (CHMOD)

Purpose
Changes the file mode of the specified file.

Example
; To Get Attributes
AX,SEG FName
DS,AX
DX,OFFSET FName
AL,e
AH,43H
2lH
Error
Attribute,CX

MOV
MOV
MOV
MOV
MOV
INT
JC
MOV

;File Name
;DS:DX pOints to ASCIIZ path name
;Indicate get
;Function-Change File Mode
;Issue request to DOS
;Error code in AX
;Save Attribute

; To Set Attributes
MOV
MOV
MOV
MOV
MOV
MOV
INT
JC

AX,SEG FName
OS,AX
OX,OFFSET FName
AL,l
AH,43H
CX,Attribute
2lH
Error

Fname

64 Dup (e)

Attribute

;File Name
;OS:DX points to ASCIIZ path name
;Indicate set
;Function-Change File Mode
;Set Attribute
;Issue request to DOS
;Error code in AX

;ASCIIZ Name
; example: I c:\dir\File.ext",e
; Fil e Attri bute
; example: aaalH 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 OOH the file's current attribute is returned in CX.

B-92

43H Change File Mode (CHMOD)
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 (01 H), 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.

B-93

44H 1/0 Oontrol 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.

8·94

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.4SH

MOV
INT
JC
MOV

BX.Handle
21H
Error
NewHandle.AX

;
;
;
;
;
;

OW
OW

; File Handle (from Open / Create)
; File Handle that duplicates Handle

Handle
NewHandle

?
?

Function Call Duplicate a Handle
Select File
Issue request to the operating system
Error code in AX
Save New 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.
Nole: 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.

B-95

46H Force a Duplicate of a Handle (FORCDUP)

Purpose
Forces the handle in ex to refer to the same file at the same position
as the handle in BX.

Example
MOV

AH.46H

MOV

BX.Handle
CX.NewHandle

MOV

INT
JC

Handle
NewHandle

21H

Error

?
?

;
;
;
;
;
;

Function Call Force Duplicate a Handle
Sel ect fil e
Select new definition of File
Issue request to the operating system
Error code in AX

; File Handle (from Open/Create)
; File Handle that duplicates Handle

Comments
On entry, BX contains the file handle. ex contains a second file
handle. On return, the ex file handle refers to the same file at the
same position as the BX file handle. If the ex 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 call59H (Get Extended
Error) for additional information about the error class, suggested
action, and location.

8-96

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
08:81.

Example
MOV
MOV
MOV

MOV
MOV
INT
JC

Drive
DName

AX.SEG DName
DS.AX
SI.OFFSET DName
DL.Drive
AH.47H
21H
Error

DB ?
DB 64 DUP(?)

: Directory Name Buffer
:
:
:
:
:

OS:SI points to buffer
Select Drive
Function-Get Current Dir
Issue request to the operating system
Error code in AX

: Drive (e=current. l=A:. 2=b: •••• )
: ASCIIZ Directory Name Returned
example: Idirl\dir2".e

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 OOH.
Error codes are returned in AX. Issue function call 59H (Get Extended
Error) for additional information about the error class, suggested
action, and location.

B·97

48H Allocate Memory

Allocates the requested number of paragraphs of memory.

Example
MOV

AH.48H

MOV
INT
JNC
MOV

BX.Paragraphs
21H
Done
AH.48H

INT

21H

MOV
MOV

BlockSeg.AX
Paragraphs.BX

; Save BlockSeg of memory

Paragraphs

BlockSeg

; Size requested in paragraphs
; (Bytes allocated is 16 * Paragraphs)
; BlockSeg address of allocated memory

;
;
;
;

Function Call Allocate Memory
Paragraphs Desired
Issue request to the operating system

;
;
;
;

Function Call Allocate memory
BX set to largest available memory
Issue request to the operating system

Done:

Comments
On entry, BX contains the number of paragraphs requested. On
return, AX:O 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.

B·98

49H Free Allocated Memory

Purpose
Frees the specified allocated memory.

Example
MOV
MOV

INT
JC

BlockSeg

AH.49H
ES.BlockSeg
21H
Error

; Function Call - Free Memory
; Set address to free
; Issue request to the operating system

; 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.

8·99

4AH Modify Allocated Memory Blocks (SETBLOCK)

Purpose
Modifies allocated memory blocks to contain the new specified block
size.

Example
MOV

AH.4AH

MOV
MOV
INT
JNC
MOV

ES.BlockSeg
BX.BlockSize
21H
Done
AH.4AH

INT

21H

MOV

Size.BX

;
;
;
;
;

Function Call Modify Allocated Memory; allocate memory
Set address to free
New size (may be larger or smaller)
Issue request to the operating system

;
;
;
;

Function Call Allocate memory
BX set to largest available Size
Issue request to the operating system

Done:

BlockSeg
BlockSize

DW
DW

?
?

; Segment address of allocated memory
; 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 31 H (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).

8·100

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,e
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+e,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+e
STI
Enable interrupts
MOV AH,4DH
Function Call - Get Return Code
INT 21H
Issue request to DOS
MOV RetCode,AX
Save return code
: To
MOV
MOV
MOV
MOV
MOV
MOV
MOV
MOV
INT
JC

Load an Overlay
AH,4BH
AL,3
CX,SEG OParms
ES,CX
BX,OFFSET OParms
CX,SEG PName
DS,CX
OX,OFFSET PName
21H
Error

Function Call - Execute a Program
Indicate load overlay
Overlay parameters
ES:BX points to parameter block
Overlay name
OS:DX points to overlay filename
Issue request to DOS
Error code in AX

B-101

4BH Load or Execute a Program (EXEC)
PName

Parms
Env@

LABEL WORD
OW
?

Cmd@
FCBl@
FCB2@

DO
DO
DO

StackSave DO
RetCode
OW

64 Dup (e)

?
?
?

OParms
LABEL WORD
Load@
OW
?
RelocFactor OW
?

; ASCIIZ Name
exampl e: lie: \di r\Fil e. ext lI.e
; Program parameters
; Environment segment address
Value of eeeeH indicates copy EXEC'ers
; Environment
; Command line address
; FCB Image to set to New PSP+5CH
; FCB Image to set to New PSP+6CH
;
;
;
;
;
;

Stack pointer save area
Program return code
(see function code 4DH for more information)
Overlay parameters
Overlay load segment address
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 8-6
and "Extended Error Codes" on page 8-7 for more information on the
codes returned from function call 59H.

8·102

4BH Load or Execute a Program (EXEC)
The following function values are allowed in AL:
Function
Value
OOH

Description
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
55, 5P, 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

B-1 03

4BH Load or Execute a Program (EXEC)
configuration parameters. The following is the format of the environment (always on a paragraph boundary):
Byte ASCIIZ string 1
Byte ASCIIZ stri ng 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-6 and "Extended Error Codes" on page B-7 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.

8·104

4CH Terminate a Process (EXIT)

Purpose
Terminates the current process and transfers control to the invoking
process.

Example
MOV
MOV
INT
INT

ErrorCode

AH.4CH
AL.ErrorCode
21H
2eH

;
;
;
;

Function Call - Terminate a Process
Set ERRORLEVEL
Issue request to DOS
Be safe if running on PC/DOS 1.1

; 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.

B-1 05

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 31 H. It returns the Exit code only
once.

Example
MOV
INT
MOV
RetCode
ExitCode
ExitType

AH.4DH
21H
RetCode.AX

: Function Call - Get Return Code
: Issue request to DOS
: Save return code

LABEL
DB
DB

: Program return code
: ERRORLEVEL value
: Method used to exit:
eeH - for normal termination
elH - for termination by Ctrl-Break
e2H - for termination as a result
of a critical device error
e3H - for termination by call 31H

WORD
?
?

Comments
The low byte of the exit code contains the information sent by the
exiting routine.

B-1 06

4EH Find First Matching File (FIND FIRST)

Purpose
Finds the first filename that matches the specified file specification.

Example
MOV
MOV
MOV
MOV
INT
MOV
MOV
MOV
MOV
MOV
INT
JC

OTA

AH,1AH
CX,SEG OTA
OS,CX
OX,OFFSET OTA
21H
AH,4EH
CX,SEG FName
OS,CX
OX,OFFSET FName
CX,Attribute
21H
Error

; Function Call - Set OTA Address
; Address buffer for found file
; Issue request to DOS
; Function Call - ASCIIZ Find First
; Directory or filename
;
;
;
;

BYTE
21 OUP(0)

OS:OX points to ASCII filename
Set Match Attribute
Issue request to DOS
Error code in AX

FileAttr
FileTime
FileOate
Fil eSi ze
FileNameExt

LABEL
DB
DB
OW
OW
DO
DB

;
;
?
;
?
;
,
?
;
?
"???????? . 11? ",0 ;

FName

64 OUP (0)

Attribute

Find return information
Reserved for DOS 4.00 to continue find
Matched files attribute low byte
Fil e time
File date
File size
Filename and extension

; ASCIIZ Name
; example: Ic:\dir\*.*",0
; Select files attribute
; Combination of following:
eee2H=Hidden
eee4H=System
ee0SH=Volume label
e010H=Oirectory

Notes:

4EH Find First Matching File (FIND FIRST)
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 11 H
(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 8-6
and "Extended Error Codes" on page 8-7 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.

8-108

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
MOV
MOV
MOV
INT
MOV
INT
JC

DTA
FileAttr
FileTime
FileDate
Fil eSi ze
FileNameExt

AH,lAH
CX,SEG DTA
DS,CX
DX,OFFSET DTA
21H
AH,4FH
21H
Error

LABEL
DB

; Function Call - Set DTA Address
; Address buffer for found file
;
;
;
;

BYTE
21 DUP(0)

Issue request
Function Call
Issue request
Error code in

., ;
";
" ;
DB?
., ;
OW?
., ;
OW?
., ;
DO?
., ;
DB
"???????? ???",0 ;

to DOS
- Find next
to DOS
AX

Find Return Information
Reserved for DOS to Continue Find
Set by Find First or Previous Find Next
Matched Files Attribute Low Byte
File Time
File Date
File Size
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.

8-109

54H Get Verify SeHing

Purpose
Returns the value of the verify flag.

Example
MOV
INT
MOV
VERIFY

AH.54H
21H
VERIFY.AL
DB

; Function Call - Get VERIFY Setting
; Issue request to DOS
; Save VERIFY State
; VERIFY State:
; e = OFF
; 1 = ON

Comments
On return, AL returns OOH if verify is OFF, 01H if verify is ON. Note
that the verify switch can be set through call 2EH (Set/Reset Verify
Switch).

B-110

56H Rename a File

Purpose
Renames the specified file.

Example
MOV
MOV
MOV
MOV
MOV
MOV
MOV
INT
JC

AH.56H
CX.SEG FName
DS.CX
DX.OFFSET FName
CX.SEG NewName
ES.CX
DI.OFFSET NewName
21H
Error

FName

64 DUP (e)

New Name

64 DUP (e)

: Function Call - ASCIIZ Rename File
; File Name
; DS:DX pOints to original name
: New Fil e Name
; ES:DI points to rename
: Issue request to DOS
; Error code in AX

; ASCIIZ Name
; example: uc:\dir\abc.lstu.a
: ASCIIZ Name
exampl e: U\di r\xyz.l stu.a

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 8-6
and "Extended Error Codes" on page 8-7 for more information on the
codes returned from function call 59H.

Network Access Rights: Requires Create access rights.

B-111

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
MOV
MOV
INT
JC
MOV
MOV

AH.57H
AL.e

BX.Handle
21H

Error
FileTime.CX
FileDate.DX

;
;
;
;
;
;
;

Function Call - Get/Set Date and Time
Indicate get
Select file
Issue request to DOS
Error code in AX
Save Time
Save Date

; To Set a File's Date and Time
MOV
MOV
MOV
MOV
MOV
INT
JC

Handle
FileTime
FileDate

AH.57H
AL.l

BX.Handle
CX. Fil eTime
DX.FileDate
21H

Error

DW
DW
DW

?
?
?

;
;
;
;
;
;
;

Function Call - Get/Set Date and Time
Indicate Set
Select file+
Set Time
Set Date
Issue request to DOS
Error code in AX

; File Handle (from Open / Create)
; File Time
; 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 8-6
and "Extended Error Codes" on page 8-7 for more information on the
codes returned from function call 59H.

B·112

59H Get Extended Error

Purpose
Returns additional error information, such as the error class,
location, and recommended action.

Example
PUSH
PUSH
PUSH
PUSH
PUSH
MOV
MOV
INT
POP
POP
POP
POP
POP
MOV
MOV

MOV
MOV

; Save Registers

OX
SI
01

ES
OS
AH.59H
BX.e

:
:
;
;

21H

OS
ES

Function Call - Get Extended Error
Version e information
Issue request to DOS
Restore registers

SI
OX
ExtError.AX
:
ErrorClass.BH :
ErrorAction.BL ;
ErrorLocation.CH;

Ext Error
ow
ErrorClass
DB
ErrorAction DB
ErrorLocation DB

?
?
?
?

:
:
;
;

Save
Save
Save
Save

error
error
error
error

code
class
action
location

DOS extended error
Class of error
Suggested action
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 21 H function calls that return an error in the carry bit
• FCB function calls that return FFH.
On return, the registers contents of OX, 51, 01, ES, Cl, and OS are
destroyed.

8·113

59H Get Extended Error
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 obtai n
additional information.
• Use the value in BL to determine the suggested action to take.

8-114

5AH Create Unique File

Purpose
Generates a unique filename, and creates that file in the specified
directory.

Example
MOV

AH.5AH

MOV
MOV
MOV
MOV
INT
JC
MOV

CX.SEG DirName
DS.CX
DX.OFFSET DirName
CX.Attribute
21H
Error
Handle.AX

DirName

DB
DB

Handle
Attribute

OW
OW

; Function Call - Create a
; Unique File
; Directory name
;
;
;
;
;

File attribute
Issue request to DOS
Error code in AX
Save file handle for following
Operations

"?? •• ??\".0 ; ASCIIZ name
"????1??1.111"
example in : I c:\dir\".0
; example out: I c:\dir\file".0
; Fil e handl e
1
; Select file's attribute
1

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 8-6
8-115

5AH Create Unique File
and "Extended Error Codes" on page 8-7 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.

8-116

5BH Create New File

Purpose
Creates a new file.

Example
MOV
MOV
MOV
MOV
MOV
INT
JC
MOV

AH.5BH
CX.SEG FName
OS.CX
OX.OFFSET FName
CX.Attribute
21H
Error
Handle.AX

; Function Call - Create a New File
; File Name

; Issue request to DOS
; Error code in AX
; Save File Handle for following operations

FName

64 OUP (a)

Handle
Attribute

OW
OW

?
?

; ASCIIZ Name
; example: "c:\dir\file".a
; Fil e Handl e
; 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 8-6
and "Extended Error Codes" on page 8-7 for more information on the
codes returned from function call 59H.
Network Access Rights: Requires Create access rights.

8-117

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

MOV
MOV
MOV
MOV
MOV
MOV
INT
JC

AL.0
BX.Handle
DX.WORD PTR
CX.WORD PTR
DI.WORD PTR
SI.WORD PTR
21H
Error

;
;
;
;
Position+0 ;
Position+2
Llength+0 ;
Llength+2
;
;

Function Call Access Lock/Unlock File
Indicate lock
Select file
Set position

;
:
:
:
Position+0 :
Position+2
Llength+0 :
Llength+2
:
;

Function Call Lock/Unlock File Access
Indicate unlock
Select file
Set position

Set length
Issue request to DOS
Error code in AX

: To Unlock a Single Range
MOV

AH.5CH

MOV
MOV
MOV
MOV
MOV
MOV
INT
JC

AL.l
BX.Handle
DX.WORD PTR
CX.WORD PTR
DI.WORD PTR
SI.WORD PTR
21H
Error

Handle
Position
Llength

DW
DD
DD

?
?
?

Set length
Issue request to DOS
Error code in AX

: Fil e Handl e
: Start of Range
; 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.

8-118

5CH Lock/Unlock File Access
AL

= OOH

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

01 HUnlock

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.

B-119

5CH Lock/Unlock File Access
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 8-6
and "Extended Error Codes" on page 8-7 for more information on the
codes returned from function call 59H.

8·120

5EOOH Get Machine Name

Purpose
Returns the character identifier of the local computer.

Example
MOV
MOV
MOV
MOV

AX, SEG CNAME
OS,AX
ox OFFSET CNAME
AX,5E99H

INT
JC
MOV
MOV

21H
Error
NameFlag,CH
NameIO,CL

: Name buffer
:
:
:
:
:
:

Function Call Get Machine Name
Issue request to DOS
Error code in AX
Save name number indicator
Save NETBIOS name number

CName
NameFlag

DB
DB

"??11????11????1",9
1

NameIO

: ASCIIZ computer name
: 9 = Name is not set
: 1 = Name is set
: 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 OOH byte. If the computer name was
never set, register CH is returned with OOH 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.

8-121

5E02H -

Set Printer Setup

Purpose
Specifies an initial string for printer files.

Example
MOV

AX.5E92H

MOV
MOV
MOV
MOV
MOV
INT
JC

BX.Index
CX.size
SI.SEG String
DS.SI
SI.OFFSET String
21H
: Issue request to DOS
Error
: Error code in AX

Index
Size
String

OW
OW

;
:
:
:
:

Function Call Set Printer Setup
Redirection List Index
String size
String Buffer

?
; Redirection List Index
N
; String size (Maximum 64)
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-6
and "Extended Error Codes" on page B-7 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 ."

8-122

5E03H -

Get Printer Setup

Purpose
Returns the printer setup string for printer files.

Example
MOV

AX.5E93H

MOV
MOV
MOV
MOV
INT
JC
MOV

BX.Index
CX.SEG String
ES.CX
OI.OFFSET String
21H
; Issue request to DOS
Error
; Error code in AX
Ssize. CX
; Save String size

Index
Ssize
String

;
;
;
;

Function Call Get Printer Setup
Redirection List Index
String Buffer

OW?
; Redirection List Index
OW?
; String size
DB
64 OUP(?) ; 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-6
and "Extended Error Codes" on page B-7 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."
B-123

SF02H Get Redirection List Entry

Purpose
Returns nonlocal network assignments.

Example
MOV
Get_Loop:
MOV
MOV
MOV
MOV
MOV
MOV
MOV
MOV
PUSH
PUSH
PUSH
INT
POP
POP
JC
MOV
MOV
MOV
POP
INC
JMP

B-124

BX,e
Index,BX
AX,5Fe2H
SI,SEG device
OS,SI
SI,OFFSET device
OI,SEG info
ES,OI
OI,OFFSET inf
BX
OX
BP
21H
BP
OX
CheckEnd
Status,BH
Type,BL
UserParm,CX
BX
BX
Get_Loop

Start at beginning of list
Get next entry
Redirection list index
; Function Call ; Get redirection list entry
"PRN" is possible
OS:SI points to local name
; ES:OI points to buffer address of network name
; Save registers
Issue request to DOS
Restore registers
Error code in AX
Save status
Save type
Save user parmameter
; Set to next entry

5F02H Get Redirection List Entry
CheckEnd:
pOP
CMP
JNE

Index
Device

BX
AX.18
Error

OW
DB

: Balance state
: End of list?
: Nol

128 DUP(?)

: Redirection list index (0 based)
: ASCIIZ device name
: examp 1e: LPTl" .0
"A:II.0
: Device status
: Bit 0=0 : Device is OK
: Bit 0=1 : Device in Error
: Bit 7-1 reserved
: User parameter
: Device type
: 3 = NET USE device
: 4 = NET USE drive
: NET USE network path
example: "\\MYNODE\CDRIVE".0
II

Status

UserParm
Type

DW
DB

Info

128 DUP(?)

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-6
and "Extended Error Codes" on page B-7 for more information on the
codes returned from function call 59H.

8-125

5F03H -

Redirect Device

Purpose
Causes a RedirectorlServer connection to be made.

Example
MOV

AX.5F03H

MOV
MOV
MOV
MOV
MOV
MOV
MOV
MOV
INT
JC

SI.SEG Device
DS.SI
SI.OFFSET Device
DI.SEG Net Path info
ES.DI
DI.OFFSET Net Path
BL.Type
CX.UserParm
21H
Error

Device

II • • • •

11,9

; Function Call ; Redirect Device
; Device Buffer
; Information Buffer
;
;
;
;

; ASCIIZ Device Name
examp 1e: LPTl" .0
"A:".e
; User Parameter
: Device Type
: 3 = NET USE Device
: 4 = NET USE Drive

;

UserParm
Type

OW
DB

Net Path

?
?

Set Type
Set User Parameter
Issue request to DOS
Error code in AX

128 DUP(e)

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 O. 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.

8-126

5F03H Redirect Device
The source string must be PRN , LPT1, LPT2, or LPT3 each ended
with a OOH. The destination string must point to a network name
string of the following form:
[\\computername\{shortname Iprintdevice}]
The destination string must be ended with a OOH.
The ASCIIZ password (O to 8 characters) for access to the remote
device should immediately follow the network string. The password must end with a OOH. A null (O length) password is considered to be no password.
• If BL = 4, the source specifies a drive letter and colon ending
with OOH, the destination specifies a network path ending with
OOH, 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 OOH. Values other than
OOH 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 (O length) password
ended with OOH 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-6 and
"Extended Error Codes" on page B-7 for more information on the
codes returned from function call 59H (Get Extended Error) .

8-127

5F03H Redirect Device
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.

8·128

5F04H -

Cancel Redirection

Purpose
Cancels a previous redirection.

Example
HOV

AX.5Fa4H

HOV
MOV
HOV
INT
JC

SI.SEG Device
DS.SI
SI.OFFSET Device
21H
; Issue request to DOS
Error
; Error code in AX

Device

; Function Call ; Cancel redirection
; Device buffer

II •••• I1,e

; ASCIIZ Device Name
example: ILPTl".a
"A:II.e

1\\Computer\Path".a

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 OOH and a password
ending with OOH, 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

8·129

5F04H Cancel Redirection
action, and location. Refer to "Responding to Errors" on page 8-6
and "Extended Error Codes" on page 8-7 for more information on the
codes returned from function call 59H.

8-130

62H Get Program Segment Prefix Address

Purpose
Returns the program prefix address.

Example
MOV

AH.62H

INT
JC

21H
Error
PSPSeg.BX

:
:
:
:
:

: Segment address of my PSP

MOV

PSPSeg

Function Call Get Program Segment Prefix Address
Issue request to DOS
Error code in AX
Save PSP address

Comments
The internal PSP address for the currently executing process is
returned in ex.

8-131

65H Get Extended Country Information

Purpose
Returns extended country information.

Example
; To get information
MOV

AH,65H

MOV

AL,InfoID

MOV

BX,CodePage

MOV

CX,SizeBuffer

MOV

DX, Count ry ID

MOV
MOV
MOV
INT
JC

DI,SEG Buffer
DS,DI
DI,OFFSET Buffer
Issue request to DOS
21H
Error
Error code in AX

;
;
;
;
;
;
;
;
;

Function Call Get extended country information
Data/function requested
(1, 2, 4, 6 or 7).
Set desired code page
(-1=current, Set by function call 6602H).
Maximum data to return
(must be >= 5)
Set desired Country ID
(-1=current, set by function call 38H).
Information return buffer

Buffer
LABEL BYTE
; Format depends on AL value
; AL=1 : Extended Country Information

;
;
;
;
;
CountryIO
OW
CodePage
OW
;
; See function call 38H for the

SizeBuffer
InfolD
CIinfoSize

B-132

DW
DB
DW

?
?

Size of data block to return
Type of info to get
amount of data that follows
(limited by CX input)
Selected CountryIO
Selected Code Page
format of the remainder of this buffer

6SH Get Extended Country Information

: AL=2 : Upper Case Table
DB
2
UpperCase@
DO
?

: Indicates Upper Case Table
: Address of Upper Case Table

: AL=4 : File Upper Case Table
DB
4
UpperCase@
DO

: Indicates File Upper Case Table
: Address of File Upper Case Table

: AL=6 : Collating Table
OB
6
Collate@
DO
?

: Indicates Collate Table
: Address of Collate Table

: AL=7 : DBCS Vector Table
DB
7
DBCS@
DO
?

: Indicates oacs Vector Table
: Address rf OBCS 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
Table

OW
OB

128
128 DUP(?)

: Table Size
; Upper case versions of 8aH to FFH

8-133

6SH Get Extended Country Information
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 ASClljn is equal to or greater than (256-tableJen),
there is an uppercase equivalent for ASCII_in in the table. If it is
lower than (256-tableJen), 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:
OW
DB

Tsize
Table

256
256 DUP(?)

: Table Size
: Sort Weights for aaH to FFH

The oacs 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
1
2

OW
DB
DB

Nx2
Start,end
Start,end

:List size
:DBCS vector 1
:DBCS vector 2

DB
DB

Start,end

:DBCS vector n
:End marker

8-134

B,a

66H Get/Set Global Code Page

Purpose
This function gets or sets the code page for the current country.
MOV

AX.6601H

INT
JC
MOV
MOV

21H
Error
GlobalCP.BX
SystemCP.DX

MOV

AX.6602H

MOV
INT
JC

BX.GlobalCP
21H
Error

;
;
;
;
;
;

Function Call Get Global Code Page
Issue request to DOS
Error code in AX
Save Global Code Page
Save DOS System Code Page

;
;
;
;
;

Function Call Set Global Code Page
New Global Code Page
Issue request to DOS
Error code in AX

;
;
;
;

Current Code Page of DOS Country Information
Code Page of DOS messages
Often the default Code Page for the
current country

GlobalCP
SystemCP

DW
DW

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.

8-135

67H Set Handle Count

Purpose
Permits more than 20 open files per process.

Example
EntryPoint:
MOV

AH.62H

INT
JC
MOV
MOV

21H
Error
ES.BX
AH.4AH

MOV
INT
JC
MOV
MOV
INT
JC

BX.paragraphs
21H
Error
AH.67H
BX.NewHandles
21H
Error

:
:
:
:
:
:
:
:
:
:
:
:
:
:

Function Call Get PSP Address
Issue request to DOS
Error code in AX
Set Segment
Function Call Set Memory Block Size
Set Size
Issue request to DOS
Error code in AX
Function Call - Set Handle Count
Set new handle count
Issue request to DOS
Error code in AX

:
:
ListSize
EQU
(Endofprogram - EntryPoint) :
Paragraphs
EQU
(ListSize / 19H)
:
End_of_program LABEL BYTE
:
:
NewHandles

Number of Handles needed
by this DOS 4.e9 process
Number of bytes
Number of paragraphs
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.

8-136

6SH 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
MOV

AH.68H
BX.Handle

INT
JC

Error

Handle

21H

:
:
:
:

Function Call - Commit File
Select file
Issue request to DOS
Error code in AX

: 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.

B·137

6CH Extended Open/Create

Purpose
Optionally opens and creates a file.

Example
MOV
MOV
MOV

AH,6CH
AL.0
BX.MOOE

;
;
;
;
;

Extended open
Reserved
Open mode
Format : eWFeeeealSSSaAAA
AAA=Access code a=Read
l=Write
;
2=Read/Write
; SSS=Sharing mode 0=Compatibility
l=OenyRead/Write
2=DenyWrite
3=OenyRead
4=OenyNone

;
:
;
:
;

I 0=Pass handle to chile, l=No inherit
F 0=INT 24H, l=Return error
on this open and any I/O to this handle
W0=No commit, l=Auto-Commit on write
Create attribute (ignored if open)
Function control, Format=e000000NNNNEEEE
NNNN=Ooes not exist action
0=Fail, l=Create
EEEE=Exists action
0=Fail, l=open, 2=Replace/Open

MOV
MOV

CX,ATTR
OX,FLAG

MOV
MOV
MOV
INT
JC

Name to open or create
SI.SEG file_name
OS,SI
SI.OFFSET file_name
21H
ERROR
; AX=Handle
CX=Action taken code
l=Fil e opened
2=File created/opened
3=File replaced/opened

;----

Mode

OW
Attr
?
Flag
OW
?
File_name
64 DUP (a)

8-138

Open mode bit
Definitions
File attributes
Function definition

6CH Extended Open/Create
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 1/0 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.

8-139

8-140

Appendix C. 1/0 Control for Devices (IOCtl)
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.

Comments
The following function values are allowed in AL:
AL
AL
AL
AL
AL
AL
AL
AL
AL
AL
AL
AL
AL
AL
AL
AL

OOH

01H

= 02H
=

03H

04H

05H

= 06H

07H

= 08H
= 09H

= OAH
=

OBH

= OCH
= ODH
=
=

OEH
OFH

Get device information (returned in DX).
Set device information (determined by DX). DH must be
ofor this call.
Read from character device
Write to character device
Read from block device
Write to block device
Get input status
Get output status
Determine if a particular block device is removable
Determine if a logical device is local or remote
Determine if a handle is local or remote
Change sharing retry count
Issue handle generic IOCtl request
Issue block device generic IOCtl request
Get logical drive
Set logical drive

IOCtl can be used to get information about devices. You can make
calls on regular files, but only function values OOH, 06H, and 07H are
defined in that case. All other calls return an "Invalid Function"
error.
Function values OOH to 08H are not supported on network devices.
Function value OBH requires the file sharing command to be loaded
(SHARE).
Many of the function calls return the carry flag clear if the operation
was successful. If an error condition was encountered, the carry flag
is set; AX contains an extended error code. (See "Extended Error
Codes" on page B-7 in Appendix B for an explanation). An explanaC-1

tion of the error codes for call 440CH can be located beginning on
page C-14 in this chapter. Information about the error, such as the
error class, location, and recommended action, is obtained by issuing
the 59H (Get Extended Error) function call.

C-2

44H 1/0 Control for Devices (IOCtl)

Calls AL = OOH and AL = 01 H
Purpose
Sets or gets device information.

Example
; To Get Device Information
MOV
MOV
MOV
INT
JC
MOV

AH.44H
AL.a
BX.Handle
21H
Error
DevInfo.DX

:
:
;
:
:
:

Function Call - IOCtl
Indicate get device information
Select device
Issue request to DOS
Error code in AX
Save device information

AH.44H
AL.l
BX.Handle
DX.DevInfo
DH.DH
21H
Error

:
:
;
;
:
;
:

Function Call - IOCtl
Indicate set device information
Select device
Device information to set
All DH bits must be off
Issue request to DOS
Error code in AX

DW
DW

: Device information
: Handle to open device

: To Set Device Information
MOV
MOV
MOV
MOV
XOR
INT
JC

DevInfo
Handle

?
?

Comments
The bits of Devlnfo are defined as follows:
15 14 13 I 12 I 11 I 10 I 9
R
E

C
T

I I I I I

B
I
N
A
R
y

R
E

S 0
D F

Reserved

I I I I I
I

S S
C C
I
L U 0
K L T N

S S
C N

C-3

44H 1/0 Control for Devices (IOCtl)
ISDEV

= 1 if this channel is a device.
= 0 if this channel is a disk file (bits 8 through 15 are 0 in
this case).
Bits 8 through 15 of OX correspond to the upper 8 bits of the
device driver attribute word.

If ISDEV - 1
EOF

= 0 if end-of-file on input.

BINARY = 1 if operating in binary mode
(no checks for Ctrl-Z).
= 0 if operating in ASCII mode
. (checking for Ctrl-Z as
end-of-file).
ISCLK = 1 if this device is the clock device.
ISNUL = 1 if this device is the null device.
ISCOT = 1 if this device is the console output.
ISCIN = 1 if this device is the console input.
CTRL = 0 if this device cannot process control
strings via calls AL=02H, AL=03H, AL=04H, and AL=05t
CTRL = 1 if this device can process control
strings via calls AL=02H and AL=03H.
Note that this bit cannot be set by
function call 44H.
If ISDEV = 0
EOF = 0 if channel has been written. Bits 0-5 are the block
device number for the channel (0 = A, 1 = B, ... ). Bits 15,
8-13,4 are reserved and should not be altered.
Note: DH must be 0 for call AL=01H.

C-4

44H 110 Control for Devices (IOCtl)
Calls AL = 02H, AL = 03H
Purpose
These two calls allow control strings to be sent or received from a
character device.

Example
; To Read a Control String from a Character Device
MOV
MOV
MOV
MOV
MOV
MOV
MOV
INT
JC
MOV

AH,44H
AL,2
BX,Handle
CX,SIZE Buffer
DI,SEG Buffer
DS,DI
DX,OFFSET Buffer
21H
Error
Count,AX

;
;
;
;
;

Function Call - 10Ctl
Indicate 10Ctl read
Select device
Set size to read
Address I/O buffer

;
;
;
;

DS:DX points to I/O buffer
Issue request to DOS
Error code in AX
Save data read count

; To Write a Control String to a Character Device
MOV
MOV
MOV
MOV
MOV
MOV
MOV
INT
JC
MOV

AH,44H
AL,3
BX,Handle
CX,SIZE Buffer
DI,SEG Buffer
DS,DI
DX,OFFSET Buffer
21H
Error
Count.A X

;
;
;
;
;

Function Call - 10Ctl
Indicate 10Ctl write
Select device
Set size to write
Address I/O buffer

;
;
;
;

DS:DX points to I/O buffer
Issue request to DOS
Error code in AX
Save data written count

?
N DUP(?)
?

; Handle to open device
; I/O buffer
; Actual I/O data transfer count

Handle DW
Buffer DB
Count DW

Comments
These are the Read and Write calls for a character device. An
"Invalid Function" error is returned if the CTRL bit is O.

C-5

44H 1/0 Control for Devices (IOCtl)
Calls AL == 04H, AL == 05H
Purpose
These two calls allow arbitrary control strings to be sent or received
from a block device.

Example
; To Read a Control String from a Block Device
MOV
MOV
MOV
MOV
MOV
MOV
MOV
INT
JC
MOV

AH.44H
;
AL.4
;
BL. Dri ve
;
CX.SIZE Buffer ;
DI.SEG Buffer
;
DS.DI
DX.OFFSET Buffer;
21H
;
Error
;
Count.AX
;

Function Call - IOCtl
Indicate IOCtl read
Select dri ve
Set Size to read
Address I/O buffer
DS:DX points to I/O buffer
Issue request to DOS
Error code in AX
Save data read count

; To Write a Control String to a Character Device
MOV
MOV
MOV
MOV
MOV
MOV
MOV
INT
JC
MOV

Drive
Buffer
Count

AH.44H
AL.5
BL.Drive
CX.SIZE Buffer
DI.SEG Buffer
DS.DI
DX.OFFSET Buffer
21H
Error
Count.AX

DB
DB
OW

?
N DUP{?)
?

;
;
;
;
;

Function Call - IOCtl
Indicate IOCtl write
Select drive
Set Size to write
Address I/O buffer

;
;
;
;

DS:DI points to I/O buffer
Issue request to DOS
Error code in AX
Save data written count

; Drive (G=current. l=A:. 2=B: •••. )
; I/O buffer
; Actual I/O data transfer count

Comments
These are the Read and Write calls for a block device. The drive
number is in BL for these calls. An "Invalid Function" error is
returned if the CTRL bit is O. An "Access-Denied" code is returned if
the drive is invalid.
C-6

44H 1/0 Control for Devices (IOCtl)
Calls AL = 06H and AL = 07H
Purpose
These calls allow you to check if a handle is ready for input or output.

Example
: To Get Input Device Status
HOV

MOV
HOV

INT
JC
HOV

AH.44H
AL.6
eX.Handle
21H

Error
Status.AL

:
:
:
:
:
:

Function Call - IOCtl
Indicate IOCtl input status
Select device
Issue request to DOS
Error code in AX
Save status

:
:
:
:
:
:

Function Call - IOCtl
Indicate IOCtl output status
Select device
Issue request to DOS
Error code in AX
Save status

: To Get Output Device Status
MOV
HOV

MOV
INT
JC
HOV

Handle
Status

AH.44H
AL.7
eX.Handle
21H

Error
Status.AL

DW
DB

?
?

: Handle to open device
: Status
: for a file:
aaH = At End of File
• FFH = Not at End of File
: for a device:
aaH = Not ready
FFH = Ready

Comments
If used for a file, AL always returns F2H until end-of-file is reached,
then always returns OOH unless the current file position is changed
through call 42H. When used for a device, AL returns FFH for ready
or 0 for not ready.

C-7

44H 1/0 Control for Devices (IOCtl)
Call AL=08H
Purpose
This call allows you to determine if a device can support removable
media.

Example
MOV
MOV
MOV

INT
JC
MOV

Drive
Dtype

AH.44H
AL.B
BL.Drive
21H
Error
Dtype.AX

DB
OW

;
;
;
;
;
;

?
?

Function Call - IOCtl
Indicate IOCtl is removable
Select drive
Issue request to DOS
Error code in AX
Save type

; Drive (e=current. l=A:. 2=B: •••• )
; Drive type
e = Drive is removable
; 1 = Drive is fixed
; eFH = Drive not valid

Comments
If the value returned in AX is 0, the device is removable. If the value
is 1, the device is fixed. The drive number should be placed in BL. If
the value in BL is invalid, an "Access-Denied" is returned. For
network devices, the error "Invalid Function" is returned.

C-8

44H 1/0 Control for Devices (IOCtl)
Call AL=09H
Purpose
This call allows you to determine if a logical device is associated with
a network directory.

Example
MOV
MOV
MOV
INT
JC
TEST
JNZ

Drive

AH.44H
AL.9
BL.Drive
21H
Error
OX. 1000H
Is_Remote

;
;
;
;
;
:
:

: Drive (0=current. l=A:. 2=B: •••• )

Function Call - IOCtl
Indicate IOCtl is remote drive
Select drive
Issue request to DOS
Error code in AX
See if local/remote
Drive is remote

Comments
On entry, BL contains the drive number of the block device you want
to check (0 = default, 1 = A, 2 = B, and so forth). The value returned in
DX indicates whether the device is local or remote. Bit 12 is set for
remote devices (1000H). Bit 12 is not set for local devices. The other
bits in DX are reserved. If disk redirection is paused, the function
returns with bit 12 not set.

e-9

44H 1/0 Control for Devices (IOCtl)
Call AL=OAH
Purpose
This call allows you to determine if a handle is for a local device or a
remote device across the network.

Example
MOV
MOV
MOV
INT
JC
TEST
JNZ

Handle

AH.44H
Al.9AH
BX.Handle
21H
Error
DX.S999H
Is_Remote

:
:
:
;
;
;
;

; Handle to open file or device

Function Call - IOCtl
Indicate IOCtl is remote handle
Select device/file
Issue request to DOS
Error code in AX
See if local/remote
Drive is remote

Comments
For remote devices, bit 15 is set (8000H). The handle should be
placed in BX. Bit 15 is not set for local devices.

C-10

44H 1/0 Control for Devices (IOCII)
Call AL == OBH
Purpose
Controls retries on sharing and lock resource conflicts.

Example
MOV
MOV
MOV
MOV
INT

NumLoops
NumRetries

AH.44H
AL.aBH
ex. NumLoops
ox. NumRetri es
21H
Error

;
;
;
;
;
;

OW
OW

; Number of times to execute loop below
; Number of times to retry on error

?
?

Function Call - IOetl
Indicate IOCtl set retry counts
Set number of loops
Set number of retries
Issue request to DOS
Error code in AX

Comments
All sharing and lock conflicts are automatically retried a number of
times before they are returned as a DOS 4.00 error or critical error.
You can select the number of retries and the delay time between
retries. On input, CX contains the number of times to execute a delay
loop, and OX contains the number of retries. The delay loop consists
of the following sequence:
XOR
ex.cx
;spin 64K times
LOOP
$
If this call is not issued, DOS 4.00 uses delay = 1 and retries = 3 as the
defaults for CX and OX. If you expect your application to cause
sharing or lock conflicts on locks that are in effect for a short period
of time, you may want to increase the values for CX and OX to minimize the number of errors actually returned to your application.

C-11

44H 1/0 Control for Devices (IOCtl)
Call AL = OCH
Purpose
This generic IOCtl function uses an open device handle to request a
device driver to perform code page switching or to get/set device
information.

Example
MOV
MOV
MOV
MOV
MOV
MOV
MOV
MOV
INT
JC

AH.44H
AL.0CH
BX.Handle
CH.Category
CL.Function
OI.SEG Packet
OS.OI
OX.OFFSET Packet
21H
Error

Handle
Category

OW
DB

Function

C-12

;
:
:
:
:
:

Function Call - IOCtl
Indicate file handle generic IOCtl request
Select device/file
Set device type
Set function
Address subfunction parameter packet

: OS:OX pOints to parameter packet
: Issue request to DOS
: Error code in AX

: Handle to open file or device
: Type of device
: 0 - Unknown (if device type not known)
: 1 - a COMx device
: 3 - CON
: 5 - a LPTx device
Function within category
For category 3 &5:
4CH = Prepare start
4DH = Prepare end
4AH = Select (Set) code page
6AH = Query (Get) selected code page
6BH = Query prepare list
For Category 3:
5FH = Set display information
7FH = Get display information

44H 1/0 Control for Devices (IOCtl)
Prepare Start: When CL=4CH, the parameter block, pointed to by
DS:DX, has the following layout:
Packet
PS_PACKET
PSJLAGS

PS_LENGTH
PS_NUMCP
PS_CPl

Label
STRUC
DW

DW
DW
DW

DW
ENDS

Word
: Prepare start packet
e
: Control flags
: Bit e = e : Download prepare
: BIT e = 1 : Cartridge prepare
: Others reserved (set to e)
(n+l)*2 : Length of rest of packet in bytes
n
: Number of code pages
?
: Code page 1

: Code page n

Notes:

1. Setting any PS_CPn to -1 tells the device driver not to change the
code page value for that position. Any other value is a code page
to be prepared.

2. n is the number of additional code pages specified in the
OEVICE= command in CONFIG.SYS. The value for n can be up
to 12.
3. For cartridge-prepares set the PS_FLAGS field to 1.
A Prepare Start request begins the preparation of a code page. It is
followed by writing data defining the code page font to the device
driver using one or more IOCtl write control string calls (AX=4403H).
It is assumed that this information will be downloaded to the device.
The stream is ended by a Prepare End. The format of the stream is
device dependent.
If the information is lost (due to a system failure or power-off), you do
not have to rewrite the prepared code page. Requesting a "refresh"
operation by issui ng a Prepare Start to the device driver with all code
page values (PS_CPn) set to a negative one (-1), restores the most
recently prepared code page information to the device. You must
follow this operation immediately with a Prepare End.

C·13

44H 1/0 Control for Devices (IOCtl)
If no data is written for a prepare operation, the driver interprets the
newly prepared code page(s) as a hardware code page. This allows
devices that support user changeable hardware fonts (usually in cartridges) to be supported.
No prepare is needed for hardware-defi ned code pages.
Prepare Start Error Codes
Code
01
22
27
29
31

Meaning
Invalid function number
Unknown command
Code page conflict (used for KEYBxx mismatch)
Device error
Device driver does not have copy of code page to download to device

Write Error Codes
Code
27
29
31

Meaning
Device not found in file, or code page not found in file
Device error
File contents not a font file, or file contents structure
damaged

Prepare End: When CL=4DH the parameter block, pointed to by
DS:DX, has the following layout:
Packet
PE_PACKET
PE_LENGTH
PE_RESVI
PE_PACKET

Label
STRUC
OW
OW

Word
; Prepare end packet
; Length of packet in bytes
; (Reserved. must be e)

ENDS

Prepare End Error Codes
Code
19
31

C-14

Meaning
Bad data read from font file
No prepare start

44H 1/0 Control for Devices (IOCtl)
Select/Query Selected Code Page: When CL = 4AH or 6AH the
parameter block, pointed to by DS:DX, has the following layout:
PACKET LABEL WORD
CP_PACKET
STRUC
CP_LENGTH
DW
CP_CPID
OW
CP_VECTORI
DB

CP_VECTORn

2+(n+l)*2
?

7.7

7.?

DB
CP_PACKET

;
;
;
;

Select/Query Selected packet
Length of packet in bytes
Code page 10
DBCS vector 1

; DBCS Vector n
; End marker
G.G

ENDS

Select/Query Selected Code Page also includes the DBCS environment vector. Some device drivers may support only the code page
value. As a result, you must check the returned length when using
this call to determine if the DBCS information is present. Only the
drivers supplied with the Asian version of DOS 4.00 provide this
support.
Select Code Page Error Codes
Code
26
27
29

Meaning
Code page not prepared
Current keyboard does not support this code page
Device error

Query Selected Code Page Error Codes
Code
26
27

Meaning
No code page has been selected
Device error

C·15

44H 1/0 Control for Devices (IOCtl)
Query Prepared List: When CL=6BH, the parameter block, pointed to
by DS:DX, has the following layout:

PACKET
QL_PACKET
QL_LENGTH
QL NUMHWCP
QL_HWCPl

QL_HWCPn
QL_NUMCP
QL_CPl

LABEL
STRUC
DW«m+l)+(n+l»*2
OW
n
OW
7

:
:
:
:

OW
OW
OW

: Hardware code page n
; Number of prepared code pages
: Prepared code page 1

: Prepared code page n

OW
ENDS

7
n

WORD
Query list packet
Length of packet in bytes
Number of hardware code pages
Hardware code page 1

Note: The device driver may return up to 12 code page values for
each type of code page (hardware or prepared) so n can be up
to 12, and m can be up to 12.
Query Prepared List Error Codes
Code
26
29

C-16

Meaning
No code pages have been selected
Device error

44H -

1/0 Control for Devices (IOCtl)
Gel/Set Display Information: When CL = 5FH or 7FH, the parameter
block, pOinted to by DS:DX, has the following layout:
VP_PACKET
VP_LEVEL

STRUC
DB

VP_RESV1
VP_LENGTH
VPJLAGS

ow
OW

a
14
a

VP_MODE

VP_RESV2
VP_COLORS
VP_WIDTH
VP_LENGTH
VP_COLS
VP_ROWS

DB
OW
OW
DW
OW
DW

VP_PACKET

ENDS

?
?
?
?
?

: Video parameters packet
: Requested info level (set to a before IOCtl
: Call)
; (Reserved. must be a)
: Length of rest of packet in bytes
: Control flags
; Bit a = a : Intense colors
: Bit a = 1 : Blink
: Others reserved (set to e)
; Video mode
: 1 = Text
; 2 = APA
: Others reserved
: (Reserved. must be a)
: Number of colors (Mono=a)
; Display width in pixels (APA mode only)
; Display length in pixels (APA mode only)
: Display width in characters
; Display length in characters

C-17

44H 1/0 Control for Devices (IOCtl)
Call AL

= OOH

Purpose
This generic IOCtl function requests a block device driver to perform
one of the following subfunctions:
•
•
•
•
•
•
•
•

Get device parameters
Set device parameters
Read track on a logical device
Write track on a logical device
Format and verify track on a logical device
Verify track on a logical device
Get access flag status
Set access flag status.

Example
MOV
MOV
MOV
MOV
MOV
MOV
MOV
INT
JC

AH.44H
;
AL.0DH
:
BL.Drive
:
CH.Category
:
CL.Function
:
DS.SEG Packet ;
DX.OFFSET Packet
21H
Error

Drive
Category

DB
DB

?
?

Function

Function Call - IOCtl
Indicate Block Device Generic IOCtl
Select Device/File
Set Device Type
Set Function
Address Subfunction Parameter Packet
Issue request to DOS
Error code in AX

: Drive (0=current. l=A:. 2=B: ••.• )
: Type of device
: 8 - Block Device
: Function within Category
; For Category 8:
40H = Set device parameters
60H = Get device parameters
41H = Write track on logical device
61H = Read track on logical device
42H = Format and verify track on a
logical device
62H = Verify track on a logical device
47H = Set access flag
67H = Get access flag

Note: Functions 43H through 46H and functions 63H through 66H are
reserved for the system.

C·18

44H 1/0 Control for Devices (IOCtI)
Comments
CH contains the major code (08H for all functions) and CL contains
the minor code (function).
Get or Set Device Parameters
To Get Device Parameters, set CL = 60H.
To Set Device Parameters, set CL = 40H.
When CL = 60H or CL = 40H, the parameter block has the following
field layout:
Packet
A_deviceParameters
Special Functions
DeviceType
DeviceAttributes
NumberOfCylinders
MediaType
DeviceBPB
TrackLayout
A_deviceParameters

Byte
Label
STRUC
DB
?
DB
?
OW
?
OW
?
DB
?
a_BPB <>
a_TrackLayout <>
ends

An explanation of each field in the parameter block is given in the
pages that follow.
SpeclalFunctlons Field
This 1-byte field is used to further define the Get and Set Device
Parameters functions.
For the Get Device Parameters function, bit 0 of the SpeclalFunctlons
field has the following meaning:
Bit 0

= 1 Return the BPB that BUILD BPS would return.
= 0 Return the default BPB for the device.

Note: All other bits must be off.
For the Set Device Parameters function bits 0, 1, and 2 of the
SpeclalFunctlons field are used.
These bits have the following meanings when CL

40H.
C-19

44H 1/0 Control for Devices (IOCII)
Bit 0

Bit 1

Bit 2

= 1 All subsequent BUILD BPB requests return DevleeBPB.
If another Set Device request is received with bit 0 reset,
BUILD BPB returns the actual media BPB.
=0 Indicates that the DevleeBPB field contains the new
default BPB for this device. If a previous Set Device
request set this bit on, the actual media BPB is returned.
Otherwise, the default BPB for the device is returned by
BUILD BPB.
= 1 Ignore all fields in the Parameter Block except the
TraekLayout field.
=0 Read all fields of the parameter block.
= 1 Indicates that all sectors in the track are the same size
and all sector numbers are between 1 and n (where n is the
number of sectors in the track.)
= 0 Indicates that all sectors in the track may not be the
same size.

Notes:
1. All other bits must be reset.
2. Set bit 2 for normal track layouts. Format Track can be more efficient if bit 2 is set.
3. Setting bits 0 and 1 at the same time is invalid and should be considered an error.
DevleeType Field
This 1-byte field describes the physical device type. Device type is
not set by IOCtl but is received from the device.
The values in this field have the following meanings:

=
1 =
2 =
3 =
4 =
5 =
6 =
7 =
C·20

320/360 KB 5.25 inch

5.25 inch, 1.2 MB
3.5 inch, 720 KB
8-inch single-density
8-inch double-density
Fixed disk
Tape drive
Other.

44H 1/0 Control for Devices (IOCtl)
DevlceAHrlbutes Field

A 1-word field that describes the physical attributes of the device.
Device attributes are not set by IOCtl but are received from the device
driver.
Only bits 0 and 1 of this field are used. They have the following
meanings:
Bit 0
Bit 1

= 1 media is not removable.
= 0 media is removable.
= 1 diskette changeline is supported.
=0 diskette changeline is not supported.

Bits 2 - 15 are reserved.
NumberOfCylinders Field

This field indicates the maximum number of cylinders supported on
the physical device, independent of the media type. The information
in this field is not set by IOCtl, but is received from the device driver.
MedlaType Field

For multimedia drives, this field indicates which media is expected to
be in the drive. This field is only meaningful for Set Device Parameters (CL = 40H) subfunction.
The MedlaType field is used only when the actual media in the drive
cannot otherwise be determined. Media type is dependent on device
type.
Regardless of the device type, a value of 0 represents the default.
For example, a 5.25-inch 1.2MB diskette drive is a multimedia drive.
The media type is defined as follows:

Quad density 1.2 MB (96 tpi) diskette

1 = Double density 320/360KB (48 tpi) diskette
The default media type for a 1.2MB drive is a quad density 1.2 MB
diskette.

C-21

44H 1/0 Control for Devices (IOCtl)
DevlceBPB Field
For the Get Device Parameters function:
• If bit 0 of the Special Functions field is set, the device driver
returns the BPB that BUILD BPB would return.
• If bit 0 of the Special Functions field is not set, the device driver
returns the default BPB for the device.
For the Set Device Parameters function:
• If bit 0 of the Special Functions field is set, the device driver is
requested to return the BPB from this field for all subsequent
BUILD BPB requests until a Set Device Parameters request is
received with bit 0 in the SpeclalFunctlons field reset.
• If bit 0 is not set, the BPB contained in this field becomes the new
default BPB for the device.
The DevlceBPB
a_BPB
BytesPerSector
SectorsPerCluster
ReservedSectors
NumberOfFATs
RootEntries
Total Sectors
MediaOescriptor
SectorsPerFAT
;

SectorsPerTrack
Heads
HiddenSectors
BigTotalSectors
Reserved
a_BPB

field has the following format:
STRUC

ow
DB
ow
DB
ow
ow
DB
ow
ow
ow

DO
DO
DB
ENDS

?
?
?
?
?
?
?
?
?
?
?
?

6 Oup (e)

TrackLayoul Field
This is a variable length table indicating the expected layout of
sectors on the media track.
DOS 4.00 device drivers do not keep a track layout table for each
logical device. The global track table must be updated (by the Set
C-22

44H -

1/0 Control for Devices (IOCtl)
Device Parameters subfunction) when the attributes of the media
change.
Note: The Set Device Parameters subfunction (CL = 40H) modifies the
track table regardless of how bit 1 of the SpeclalFunctlons field
is set.
For Get Device Parameters, this field is not used. The track layout is
used by subsequent Read/Write Track, Format/Verify Track and Verify
Track functions.
The following example shows how this field is formatted:
Total sectors-------ISectorCount
Sector l-----------ISectorNumber_l
SectorSize_l

ow
ow

IH
OW 2eaH

Sector 2-----------ISectorNumber_2
SectorSize_2

Sector 3-----------ISectorNumber_3
SectorSize_3

Sector 4-----------ISectorNumber_4

SectorSre_4

Sector n-----------ISectorNumber_n
SectorSize_n

2H
OW 2eeH

3H
OW 2eaH
4H
OW 2eaH

n
OW 2eeH

Note: All values are in hexadecimal.
The total number of sectors is indicated by the SectorCount field.
Each sector number must be unique and in a range between 1 and n
(sector count). As shown in the example above, the first sector
number is 1 and the last sector number is equal to the sector count
(n). If bit 2 of the Special Functions field is set, all sector sizes, which
are measured in bytes, must be the same. See the description of bit
2 under the SpeclalFunctlon field.
Note: The DevlceType, DevlceAHrlbutes, and NumberOfSectors fields
should be changed only if the physical device has been
changed.

C-23

44H 1/0 Control for Devices (IOCtl)
Read/Write Track on Logical Device
To read a track on a logical device, set CL

= 61 H.

To write a track on a logical device, set CL = 41 H.
The parameter block has the following layout when reading or writing
a track on a logical device.
Packet
a_ReadWriteTrackPacket
Special Functions
Head
Cylinder
FirstSector
NumberOfSectors
TransferAddress
A_ReadWriteTrackPacket

LABEL
STRUC
DB
DW
DW
DW
DW
DO
ENDS

BYTE
?
?
?
?
?

Notes:
1. All bits in the SpeclalFunctlons field must be reset.
2. The value in the FlrstSector field and the NumberOfCylinders field
is O-based. For example, to indicate sector 9, set the value to 8.
FormatlVerlfy Track on Logical Drive (IOCtl Write)
To format and verify a track, set CL

= 42H.

To verify a track, set CL = 62H.
The parameter block has the following layout when formatting a track
or verifying a track on a logical drive.
PACKET
AJormatPacket
Special Functions
Head
Cylinder
AJormatPacket

C-24

LABEL
STRUC
DB
DW
OW
ENDS

BYTE
?
?
?

44H 1/0 Control for Devices (IOCtl)
On entry, bit 0 of the SpecialFunctions field has the following
meanings:
Bit 0 = 1 Format status check call to determine if a
combination of number-of-tracks and
sectors-per-track is supported.

0 Format IVerify track call.

To determine if a combination of number-of-tracks and sectors- pertrack is supported, a Set Device Parameters call must be issued with
the correct BPB for that combination before issuing the Format Status
call. The device driver can then return the correct code to indicate
what is supported. The value returned in the Special Functions field
for a Format Status Check call are:

o =

This function is supported by the
ROM BIOS. The specified combination of
number-of-tracks and sectors-per-track is
allowed for the diskette drive.

This function is not supported by
the ROM BIOS.

2 = This function is supported by the
ROM BIOS. The specified combination of
number-of-tracks and sectors-per-track is
not allowed for the diskette drive.

This function is supported by the
ROM BIOS, but ROM BIOS cannot determine
if the numbers-of-tracks and
sectors-per-track are allowed because
the diskette drive is empty.

C-25

44H 1/0 Control for Devices (IOCtl)
To format a track:
1. Issue the Set Device Parameters function call.
2. Issue the Format Status Check function call to validate the
number-of-tracks and sectors-per-track combination. Ignore the
result if the value returned is 1, because the ROM BIOS does not
support this function.
3. Issue the Format/Verify Track function call with the
Special Functions bit 0 reset for each track on the medium.
Get/Set AccessFlag Status
To get the access flag status of a fixed disk, set CL=67H.
To set the access flag status of a fixed disk, set CL = 47H.
The parameter block has the following layout when getting or setting
the access flag status of a fixed disk:
PACKET
a_DiskAccess_Control
Special Functions
DiskAccessJlag

LABEL
STRUC

DB
DB

BYTE

e
?

: e = Disallow
: Other value

disk access

= allow disk access

If the media has not been formatted or has an invalid boot record, the
system will not allow disk 110 for the media. This ensures data integrity of fixed media. Since formatting a media is a special activity, and
is needed to perform disk I/O for unformatted media, additional functions to control the disk access flag are necessary. A format utility
should issue "Set the access flag status (CL = 47H)" with
DiskAccess_Flag = non-zero value to access the unformatted media.
When every format operation is a success, leave the access flag
status as it is to allow further disk 110 from general users. If format
fails, issue "Set the access flag status (CL = 47H)" with
DiskAccess_Flag = zero in order to block further media access. To
get the current status of the system disk access flag, issue "Get the
access flag status (CL = 67H)". If DiskAccess_Flag = zero, disk 110
is not allowed for the media.

C·26

44H 1/0 Control for Devices (IOCtl)
Can AL == OEH
Purpose
Allows the device driver to determine if more than one logical drive is
assigned to a block device. When this call is issued, a drive number
is passed in BL on input.

Example
MOV
HOV

MOV
INT
JC
CMP
JE
MOV

Drive
ActiveDrive

AH.44H
AL.eEH
BL.Drive
21H
Error
AL.e
Single_Drive
ActiveDrive.AL

:
:
:
:
:
:
:
:

DB
DB

: Drive (e=current. l=A:. 2=B: •.•. )
: Current drive letter for this device
: (1=A:. 2=B:. • •• )

?
?

Function Call - IOCtl
Indicate Logical Drive Check
Select Drive
Issue request to DOS
Error code in AX
Only one drive letter for this device?
Yes!
Save Active Drive info

Comments
If the block device has more than one logical drive letter assigned to
it, on output a drive number corresponding to the last drive letter that
was used to reference the device is returned in AL. If only one drive
letter is assigned to the device, 0 is returned in AL by this call.

C-27

44H 1/0 Control for Devices (IOCtl)
Call AL == OFH
Purpose
This call requests the device driver to change the next logical drive
letter that will be used to reference a block device.

Example
MOV
MOV
MOV
INT
JC
CMP
JE
MOV

Drive
ActiveDrive

AH.44H
AL.eFH
BL.Drive
21H
Error
AL.e
Single_Drive
ActiveDrive.AL

;
;
;
;
;
;
;
;
;

DB
DB

; Drive (e=current. l=A:. 2=B: •••• )
; Current drive letter for this device
; (1=A:. 2=B: •••• )

Function Call - IOCtl
Indicate Set Logical Drive
Set Drive
Issue request to DOS
Error code in AX
Only one drive letter for this device?
Yes!
Save Active Drive info
(should be the same as BL in)

Comments
When copying diskettes on a drive whose physical drive number has
more than one logical drive letter assigned to it (for example, copying
on a single drive system), DOS 4.00 issues diskette swap prompts to
tell you which logical drive letter is currently referencing the physical
drive number. As the drive changes from source to target, DOS 4.00
issues the message:
"Insert diskette for drive X: and strike any key
when ready.
II

It is possible to avoid this message by issuing call AL = OFH (Set
Logical Drive).
To avoid the DOS 4.00 diskette swap message, set BL to the drive
number that corresponds to the drive letter that will be referenced in
the next 110 request.

C-28

44H 1/0 Control for Devices (IOCtl)
Note: You can determine the last logical drive letter assigned to the
physical drive number by issuing call AL = OEH.

Because any block device can have logical drives, this call should be
issued before all 1/0 operations involving more than one drive letter;
otherwise, the DOS 4.00 message may be issued.

C-29

C-30

Appendix D. Expanded Memory Support
Expanded memory is memory addressable through a combination of
an Expanded Memory Specification (EMS) device driver and an
EMS-capable hardware adapter.
The table below describes the Lotusl/ntellMicrosoft (LIM) Expanded
Memory Manager Specification Version 4.0 functions and shows you
which ones are supported by DOS 4.00. For detailed information and
guidelines on the use of these calls, refer to the LIM Specification.

AH = 40H
AH = 41H

Interface
App
App

DOS 4.00
Support
Yes
Yes

AH = 42H

App

Yes

4
5

AH = 43H
AH = 44H

App
App

Yes
Yes

6
7
8

App
App
App
App

Yes
Yes
Yes
Yes

10
11
12

AH = 45H
AH = 46H
AH = 47H
AH = 48H
Reserved
Reserved
AH = 4BH

App

Yes

AH = 4CH

App

Yes

AH = 4DH

App

Yes

15
16

AH = 4EH
AH = 4FH

App
App

Yes
Yes

LIM
Spec.
1
2

INT
67H

Description
Get status
Get page frame
address
Get unallocated page
count
Allocate pages
Map/unmap handle
page
Deallocate pages
Get EMM version
Save page map
Restore page map

Get EMM Handle
count
Get EMM Handle
pages
Get all EMM handle
pages
Get/Set page map
Get/set partial page
map

D-1

LIM
Spec.
17

67H

Interface
App

DOS 4.00
Support
Yes

18
19

AH = 51H
AH = 52H

App
App

Yes
No

20
21
22

AH = 53H
AH = 54H
AH = 55H

App
App
App

Yes
Yes
Yes

56H

App

Yes

57H

App

Yes

58H

App

Yes

AH = 59H

Yes

27
28

AH
AH

=
=

5AH
5BH

App

Yes
Yes

5CH

App

Yes

50H

App

Yes

D·2

INT
AH

50H

Description
Map/unmap multiple
handle pages
Reallocate pages
Get/set handle attributes
Get/set handle name
Get handle directory
Alter page map and
jump
Alter page map and
call
Move/exchange
memory region
Get mappable physical address array
Get expanded
memory hardware
information
Allocate new pages
Alternate page map
register set
Prepare expanded
memory hardware
for warm boot
Enable/disable OSIE
function set

Index
Special Characters

; (fi lename separator) 8-57
. (filename separator) 8-57
.8AK 7-5
.COM files 2-3
.COM programs 8-4
.EXE 8-3
.EXE programs 6-6
.Ll8 extension 7-2
.08J extension 8-2
< (filename terminator) 8-57
(-) hyphen (DE8UG prompt) 10-1
(') single quotation 10-14
(") double quotation 10-14
+ (add) 7-4
+ (filename separator) 8-57
I (filename terminator) 8-57
* (copy) 7-4
- (erase) 7-4
-+ (replace) 7-4
-* (remove) 7-4
/ (filename terminator) 8-57
] (filename terminator) 8-57
, (filename separator) 8-57
, (filename terminator) 8-57
> (filename terminator) 8-57
: (filename separator) 8-57
= (filename separator) 8-57
II (filename terminator)
8-57
[ (filename terminator) 8-57
[] square brackets (DE8UG) 10-7

absolute disk read/write (INT
25H/26H) A-7
AC flag set condition 10-36
Access, Lock/Unlock File 8-118
accessing files
using file control blocks 4-1
using file handles 3-1
accessing the disk 2-1
accumulator register 8-4
adding a module 7-11
address (INT 22H), terminate A-2
address (INT 23H), Ctrl- 8reak
exit A-2
address, default disk transfer 6-6
address, memory map 6-2
Address, Set Disk Transfer 8-41
AL function values C-1
align types of segment 8-33
allocate command, EMS 10-48
Allocate Memory 8-98
Allocated Memory 810cks
(SET8LOCK), Modify 8-100
Allocated Memory, Free 8-99
allocating paragraph space 8-14
Allocation Table Information 8-42
Allocation Table Information for
Specific Device 8-43
APPEND A-13
ASCII in Dump command 10-11
ASCII mode, 110 in 5-5
ASCIIZ filename string 3-1
Assemble command 10-6
Assembler Language, IBM PC 8-4
attribute field 11-4
attribute, file 3-4
auxiliary carry flag 10-36
Auxiliary Input 8-15

X-1

Auxiliary Output

B-16

bytes in directory entry

3-4

base pOinter B-5
base register B-4
BASIC.LlB 7-7
BASNEW.LlB 7-7
binary mode, 110 in 5-5
BIOS parameter block (BPB) 11-3,
11-16
bit fields B-79
block device driver 11-1
BIOS parameter block (BPB)
array 11-3
drive letters 11-2
input/output request 11-20
installing a block device 11-3
installing a character
device 11-2
media descriptor byte 11-3
random I/O 11-1
Block Read, Random B-52
Block Write, Random B-54
block, parameter 6-7
blocks, memory 6-1
book, organization of this 1-1
boot record 2-1
boot record, extended BPB 11-19
boot sector format of BPB 11-16
BP (base pointer) B-5
BPB (see BIOS parameter block)
buffer memory (disk transfer
area) 4-5
Buffered Keyboard Input B-22
build BPB request 11-16
boot sector format 11-16
extended boot record 11-19
extended BPB structu re 11-17
media type 11-16
busy bit 11-8
byte, media descriptor 11-14
bytes in a request header 11-7

CALL FAR A-4
calls for code page switching C-12
calls, using DOS 4.00 function B-3
cancel all files A-12
cancel file A-12
Cancel Redi rection B-129
capital sensitive option 8-25
carry flag 10-36
Change Current Directory
(CHOIR) B-76
Change File Mode (CHMOD) B-92
character device driver 11-1
CLOCKS device 11-29
installing a new CON
device 11-2
output request 11-23
terminating the input
queue 11-24
type-ahead input buffer 11-23
character input/output flush
request 11-24
character input/output status 11-23
Check Standard Input Status B-23
check, ctrl-break B-66
check, library consistency 7-3,
7-13
CHECKSUM 6-9
clear condition of flag 10-36
Clear Keyboard Buffer and Invoke a
Keyboard Function B-24
clock device bit 11-5
CLOCKS device 11-29
Close a File Handle B-85
CLOSE call 11-25
Close File 8-29
cluster number, first 3-6
cluster, sectors per 2-2
CODE class name 8-15
code libraries, object 7-1

X-2

Code of a Subprocess (WAIT), Get a
Return B-106
code page switching C-12
Code Page, Get/Set Global B-135
code segment B-5
codes (INT 24H). error A-3
codes, extended error B-7
codes, function A-11
CodeVlewoption 8-13
combined-types of segments 8-34
command code 11-8
command files from SI format
option 2-3
command line 6-8
command line format, LIB 7-5
command processor 6-10
command symbols 7-4
COMMAND.COM 2-3, 6-1
command, DEBUG
A (Assemble) 10-6
C (Compare) 10-9
D (Dump) 10-11
E (Enter) 10-14
F (Fill) 10-17
G (Go) 10-19
H (Hexarithmetic) 10-22
I (Input) 10-23
L (Load) 10-24
M (Move) 10-27
N (Name) 10-29
o (Output) 10-31
P (Proceed) 10-32
Q (Quit) 10-33
R (Register) 10-34
S (Search) 10-38
T (Trace) 10-40
U (Unassemble) 10-42
W (Write) 10-45
XA (EMS Allocate) 10-48
XD (EMS Deallocate) 10-49
XD (EMS Map) 10-50
XD (EMS Status) 10-51
Commit File B-137

communication area 6-2
Compare command 10-9
compatibility mode B-81
compiler compatibility 8-24
computer name B-121
CONFIG.SYS 11-11
consistency check, library 7-3,
7-13
Console 110, Direct B-18
Console Input with Echo B-13
Console Input without Echo B-20
control block 6-1
Control for Devices, 110 B-94, C-1
control strings 11-5
control values, 110 5-5
control-break routine 6-12
controlling data loading 8-16
converting file formats 9-1
copying line numbers 8-21
count register 8-5
Country Dependent Information, Get
or Set B-71
Country Information, Get
Extended B-132
Create a File (CREAT) B-77
Create Fi Ie B-37
Create New File B-117
Create Subdirectory (MKDIR) B-74
Create Unique File B-115
creating map files 8-3
critical error handler vector (INT
24H) A-3
CALL FAR A-4
device header format A-7
disk error A-5
error codes A-3
FAIL request A-6
hardware error A-3
IGNORE request A-7
ignore response A-4
IRET execution A-4
critical error situation 6-11
cross-reference list 7-12

X-3

CS register B-5
CS:IP conversions 9-3
ctrl-break checking B-66
Ctrl-Break routine 6-12
Ctrl- Break exit address (INT
23H) A-2
Current Directory, Get B-97
Current Disk B-40
CY flag set condition 10-36

D
data area 2-4
data files, storage of 2-4
data loading option 8-16
data register B-5
data segment B-5
Date and Time, Get/Set
File's B-112
date in a directory structure 3-6
Date, Get B-58
Date, Set B-59
date, system 6-13
DBCS vector B-134, C-15
deallocate command, EMS 10-49
DEBUG
.EXE extension 10-5
.HEX extension 10-5
(DEBUG prompt) hyphen
(-) 10-1
activating a command 10-2
ASCII in Dump command 10-11
calculating hexadecimal 10-22
changing a flag 10-36
comparing memory 10-9
contents of a register 10-35
delimiters as separators 10-2
DISKCOMP utility 10-1
displaying memory 10-11
ending DEBUG program 10-33
error messages 10-52
executing the program 10-19
FAR prefix 10-7
hexadecimal in Dump
command 10-11

X-4

DEBUG (continued)
list of DEBUG commands 10-3
list of flag settings 10-36
loading a file 10-24
NEAR prefix 10-7
overlapping moves 10-27
re-displaying Load
command 10-24
starting the DEBUG
program 10-1
starting without a file specification 10-29
stopping the program 10-19
syntax error 10-2
terminating a command 10-2
unassembling
instructions 10-42
utility diskette 10-1
writing to absolute
sectors 10-46
8086/8088 code rules 10-6
DEBUG command
A (Assemble) 10-6
C (Compare) 10-9
D(Dump) 10-11
description of 10-2
E (Enter) 10-14
F (Fill) 10-17
G (Go) 10-19
H (Hexarithmetic) 10-22
I (Input) 10-23
L (Load) 10-24
M (Move) 10-27
N (Name) 10-29
o (Output) 10-31
P (Proceed) 10-32
Q (Quit) 10-33
R (Register) 10-34
S (Search) 10-38
T (Trace) 10-40
U (Unassemble) 10-42
W (Write) 10-45
XA (EMS Allocate) 10-48
XD (EMS Deallocate) 10-49

DEBUG command (continued)
XD (EMS Map) 10-50
XD (EMS Status) 10-51
DEBUG.COM 1-2
DEBUG.COM utility 10-1
default libraries 8-4, 8-23
Definition File [.DEF]: (prompt) 8-4
Delete a File from a Specified Directory (UNLINK) 8-89
Delete File B-34
denynone mode B-83
DenyRead mode 8-83
DenyRead/Write mode 8-82
DenyWrite mode 8-82
descriptor byte, media 11-14
destination index B-6
device driver
block device 11-1
build BP8 request 11-16
character device 11-1
CLOCKS device 11-29
creating a 11-1
definition of 11-1
description of 11-3
device header 11-3
fields in request header 11-7
first block 11-2
initializating a device 11-2
installing a block device 11-3
installing a character
device 11-2
installing a new CON
device 11-2
interrupt routines 11-7
logical drive check C-27
request data 11-9
request header 11-7
single block 11-2
strategy routine 11-6
device driver control channel 5-3
device driver header 11-4
attribute field 11-4
clock device bit 11-5
control strings 11-5

device driver header (continued)
definition of 11-4
format of 11-4
input device, standard 11-6
10Cti bit 11-5
name/unit field 11-6
next device header field 11-4
NUL device 11-6
open/close removable media
bit 11-5
output device, standard 11-6
pOinter to interrupt routine 11-6
poi nter to strategy routi ne 11-6
device driver, EMS 0-1
device file handle, standard 3-3
device header format (INT
24H) A-7
device I/O
block device, read/write to
a C-6
character device, read/write to
a C-5
control channel 5-3
device redirection 5-3
display 5-1
keyboard 5-2
local or remote C-9
device, local or remote C-10
Device, Redirect 8-126
DeviceAttributes field C-21
Device8P8 field C-22
Devices, I/O Control for 8-94, C-1
DeviceType field C-20
01 flag clear condition 10-36
01 register 8-5
direct access to media A-7
Direct Console I/O 8-18
Direct Console Input without
Echo 8-19
direction flag 10-36
directory
entry structure 3-4
Directory (CHOIR), Change
Current 8-76

x-s

Directory, Get Current 8-97
directory, root 2-3
disk
absolute disk read/write (INT
25H/26H) A-7
default transfer address 6-6
drive number 2-5
hard error on disk A-5
sectors on a disk 2-2
disk accessing 2-1
disk file, temporary 8-5
disk format 2-1
boot record 2-1
data area 2-4
disk directory 2-3
file allocation table (FAT) 2-2
root directory 2-3
Disk Free Space, Get 8-69
disk I/O warning A-8
Disk Reset 8-25
Disk Transfer Address (DTA),
Get 8-63
Disk Transfer Address, Set 8-41
disk transfer area (DTA) 4-5
Disk, Current 8-40
disk, pause to change 8-27
Disk, Select 8-26
DISKCOMP utility 10-1
diskette, DE8UG utility 10-1
diskette, utilities 1-2
Display Output 8-14
Display String 8-21
displaying process phase 8-20
ON flag set condition 10-36
done bit 11-8
DOS 4.00 format command 2-1
DOS 4.00 function dispatcher 6-6
DOS 4.00 interrupts
absolute disk read/write (INT
25H/26H) A-7
critical error handler vector (INT
24H) A-3
Ctrl-8reak exit address (INT
23H) A-2

X-6

DOS 4.00 interrupts (continued)
function request (INT 21 H) A-1
multiplex interrupt (INT
2FH) A-10
program terminate (INT
20H) A-1
terminate address (INT
22H) A-2
terminate but stay resident (INT
27H) A-9
DOS 4.00 organization of book 1-1
DOS 4.00 registers, see registers,
DOS 4.00
DOS 4.00 system fi les 2-3
DOS 4.00 utilities diskette 1-2
DOS 4.00 Version Number,
Get 8-64
DOS 4.00, hardware supported
by 1-3
DOS 4.00, new features of 1-2
OS register 8-5
DTA (see disk transfer area)
Dump command 10-11
Duplicate a File Handle
(DUP) 8-95

E
Echo, Console Input with 8-13
Echo, Console Input without 8-20
Echo, Direct Console Input
without 8-19
EI flag set condition 10-36
EMS (see expanded memory specification)
EMS command
allocate 10-48
deallocate 10-49
map 10-50
status 10-51
EMS-capable hardware
adapter 0-1
end of status A-13

ending the library manager
session 7-2
ending the link session 8-2
enhancements to DOS 4.00 1-2
Enter command 10-14
Entry, Search for First B-30
Entry, Search for Next B-32
environment string,
subprogram 6-7
erase a module 7-11
error
critical error situation 6-11
DEBUG error messages 10-52
extended error codes B-7
fix-up overflow error 8-35
hard error on disk A-5
I ibrary manager error
messages 7-15
LINK error messages 8-37
print error codes A-11
segment group error 8-35
syntax error, DEBUG 10-2
error bit 11-8
error code information B-6
error codes, status word 11-9
error handler vector (lNT 24H), critical A-3
Error, Extended B-113
error, segment group 8-35
ES register B-5
EXE extension, DEBUG 10-5
executable files, packing 8-17
executable/relocatable file 8-1
Execute a Program (EXEC), Load
or B-101
executing a subprogram 6-7
EXE2BIN.EXE 1-2, 9-1
exit program A-1
expanded memory specification
(EMS) D-1
extended BPB structure 11-17
Extended Country Information,
Get B-132

extended error codes B-7
Extended Error, Get B-113
extended file control block 4-5
Extended Open/Create B-138
extended 25H or 26H A-8
extra segment B-5

F
FAIL request A-6
failures, print A-13
FAR prefix, DEBUG 10-7
FAT (see file allocation table)
FCB (see file control block)
FCBS command 4-6
field
attribute 11-4
DeviceAttributes C-21
DeviceBPB C-22
DeviceType C-20
MediaType C-21
NumberOfCylinders C-21
Special Functions C-19
TrackLayout C-22
field in parameter block C-19
fields in device header 11-4
fields in file control block 4-1
file
.EXE file, DEBUG 10-5
.HEX extension, DEBUG 10-5
file format 9-1
in ASCII mode 5-5
LINK response file 8-8
Linker list file 8-3
map file 8-31
object file 7-1
response file 7-8
sharing using SHARE
command 4-6
temporary disk file 8-5
File (FIND FIRST), Find First
Matching B-107
File (FIND NEXT), Find Next
Matching B-109

X-7

File Access, Lock/Unlock 8-118
file activity
accessing with file control
blocks 4-1
accessing with file handle 3-1
changing a file 4-8
converting file formats 9-1
device redirection 5-3
finding a file 4-8
library file, creating a 7-9
linking object files 8-1
packing executable files 8-17
preparing files for
CodeView 8-13
file allocation table (FAT) 2-2
file attribute 3-4
file control block (FC8) 4-1
extended 4-5
format 4-3
logical record size 4-3
opened fi Ie 4-1
record number 4-4
reserved fields 4-1
unopened file 4-1
File Handle (DUP), Duplicate
a 8-95
File Handle, Close a 8-85
file handles 3-2
file loading, run 8-19
file sharing using SHARE
command 4-6
File Size 8-48
fi Ie system activities 5-3
file, cancel A-12
File, Close 8-29
File, Commit 8-137
File, Create 8-37
File, Create New 8-117
File, Create Unique 8-115
Fi Ie, Delete 8-34
File, Open 8-27
File, Open a 8-78
File, Rename 8-38

x-a

File, Rename a 8-111
file, submit A-12
File's Date and Time,
Get/Set 8-112
filename
ASCIIZ string 3-1
naming a file 3-1
of subdirectory 3-4
separators 8-57
terminators 8-57
Filename, Parse 8-56
FILES command 3-2
files for CodeView, preparing 8-13
files, cancel all A-12
files, physical location of 2-2
Fill command 10-17
Find First Matching File (FIND
FIRST) 8-107
Find Next Matching File (FIND
NEXT) 8-109
first block device driver 11-2
First Matching File (FIND FIRST),
Find 8-107
fix-up overflow error 8-35
flags 8-5
flags in register command 10-36
flags, display 10-35
flush function call parameter 11-24
Force a Duplicate of a Handle
(FORCDUP) 8-96
format
of build 8P8 request 11-16
of calls for code page
switching C-12
of DE8UG utility 10-1
of device header 11-4
of device header (INT 24H) A-7
of disk/diskette 2-1
of extended boot record 11-19
of extended 8P8
structure 11-17
of file control block 4-3
of file format 9-1
of generic IOCtl request 11-27

format (continued)
of get logical device
request 11-28
of initialization request 11-11
of input/output request 11-20
of media check request 11-13
of nondestructive input
request 11-22
of open or close request 11-25
of removable media
request 11-25
of request header 11-7
of set logical device
request 11-28
format option, S/ 2-3
format/verify a track C-24
fragments, program code B-4
Free Allocated Memory B-99
function calls
Allocate Memory B-98
Allocation Table
Information B-42
Allocation Table Information for
Specific Device B-43
Auxiliary Input B-15
Auxiliary Output B-16
Buffered Keyboard Input B-22
Cancel Redirection B-129
Change Current Directory
(CHOIR) 8-76
Change File Mode
(CHMOD) B-92
Check Standard Input
Status B-23
Clear Keyboard 8uffer, Invoke a
Keyboard Function B-24
Close a File Handle B-85
Close File B-29
Commit File B-137
Console Input with Echo 8-13
Console Input without
Echo B-20
Create a File (CREAT) B-77
Create File B-37

function calls (continued)
Create New File B-117
Create New Program
Segment 8-51
Create Subdirectory
(MKDIR) B-74
Create Unique File B-115
Current Disk B-40
Delete a File from a Specified
Directory (UNLINK) B-89
Delete File B-34
Di rect Console I/O B-18
Direct Console Input without
Echo B-19
Disk Reset B-25
Display Output B-14
Display String B-21
Duplicate a File Handle
(DUP) B-95
Extended Open/Create 8-138
File Size B-48
Find First Matching File (FIND
FIRST) B-1 07
Find Next Matching File (FIND
NEXT) 8-109
Force a Duplicate of a Handle
(FORCDUP) B-96
Free Allocated Memory B-99
Get a Return Code of a Subprocess (WAIT) 8-106
Get Current Directory B-97
Get Date B-58
Get Disk Free Space B-69
Get Disk Transfer Address
(DTA) 8-63
Get DOS 4.00 Version
Number 8-64
Get Extended Country Information B-132
Get Extended Error B-113
Get Interrupt Vector B-68
Get Machine Name B-121
Get or Set Country Dependent
Information B-71

X-I

function calls (continued)
Get Printer Setup 8-123
Get Program Segment Prefix
Address 8-131
Get Redirection List
Entry 8-124
Get Time 8-60
Get Verify Setting 8-110
Get/Set File's Date and
Time 8-112
Get/Set Global Code
Page 8-135
Get/Set System Value 8-66
110 Control for Devices 8-94,
C-1
Load or Execute a Program
(EXEC) 8-101
Lock/Unlock File Access 8-118
Modify Allocated Memory 810cks
(SET8LOCK) 8-100
Move File Read Write Pointer
(LSEEK) 8-90
Open a File 8-78
Open File 8-27
Parse Filename 8-56
Printer Output 8-17
Program Terminate 8-12
Random alock Read 8-52
Random 810ck Write 8-54
Random Read 8-44
Random Write 8-46
Read from a Fi Ie or
Device 8-86
Redirect Device 8-126
Remove Subdirectory
(RMDIR) 8-75
Rename a File 8-111
Rename File 8-38
Search for First Entry 8-30
Search for Next Entry 8-32
Select Disk 8-26
Sequential Read 8-35
Sequential Write 8-36
Set Date 8-59

X-10

function calls (continued)
Set Disk Transfer Address 8-41
Set Handle Count 8-136
Set Interrupt Vector 8-50
Set Printer Setup 8-122
Set Relative Record Field 8-49
Set Time 8-61
Set/Reset Verify Switch 8-62
Terminate a Process
(EXIT) 8-105
Terminate Process and Remain
Resident 8-65
Write to a File or Device 8-87
function calls, using DOS 4.00 8-3
function codes A-11
function dispatcher, DOS 4.00 6-6
function request (INT 21H) A-1

G
general registers, list of 8-4
generic 10Cti request C-18
format/verify a track C-24
get device parameters C-19
read track on a logical
device C-24
set device parameters C-19
verify a track C-24
write track on logical
device C-24
Get a Return Code of a Subprocess
(WAIT) 8-106
Get Current Directory 8-97
Get Date 8-58
get device information C-3
get device parameters C-19
Get Disk Free Space 8-69
Get Disk Transfer Address
(DTA) 8-63
Get DOS 4.00 Version
Number 8-64
Get Extended Country
Information 8-132

Get Extended Error 8-113
get installed state A-12
Get Interrupt Vector 8-68
get logical device function
call 11-28
Get Machine Name 8-121
Get or Set Country Dependent Information 8-71
Get Printer Setup 8-123
Get Program Segment Prefix
Address 8-131
Get Redirection List Entry 8-124
Get Time 8-60
Get Verify Setting 8-110
Get/Set File's Date and
Time 8-112
Get/Set Global Code Page 8-135
Get/Set System Value 8-66
Global Code Page, Get/Set 8-135
Go command 10-19
group pseudo-op instruction 8-35

H
Handle (FORCDUP), Force a Duplicate of a 8-96
Handle Count, Set 8-136
handle is local or remote C-10
handler vector (INT 24H), critical
error A-3
handler, installing a A-17
handles, file 3-2
hard error on disk A-5
hardware supported by DOS
4.00 1-3
header, device driver 11-4
attribute field 11-4
clock device bit 11-5
control stri ngs 11-5
definition of 11-4
format of 11-4
input device, standard 11-6
10Cti bit 11-5
name/unit field 11-6

header, device driver (continued)
next device header field 11-4
NUL device 11-6
open/close removable media
bit 11-5
output device, standard 11-6
pointer to interrupt routine 11-6
pOinter to strategy routine 11-6
help option 8-18
HEX extension, DE8UG 10-5
hexadecimal in Dump
command 10-11
Hexarithmetic command 10-22

I/O
control channel 5-3
control values 5-5
device tasks 5-1
Direct Console I/O 8-18
in ASCII 5-5
in binary 5-5
to from/console device 3-3
I/O Control for Devices (IOCtl) C-1
AL function values C-1
block device, read/write to
a C-6
character device, read/write to
a C-5
code page switching C-12
descri ption of C-1
device is local or remote C-9
generic 10Cti request C-18
format/verify a track C-24
get device parameters C-19
read track on a logical
device C-24
set device parameters C-19
verify a track C-24
write track on logical
device C-24
get device information C-3
handle is local or remote C-10

X-11

110 Control for Devices (IOCtl) (continued)
input device status C-7
lock conflicts C-11
logical drive check C-27
output device status C-7
removable media
determination C-8
set device information C-3
set logical drive C-28
sharing and lock conflict
retries C-11
IBM Library Manager/2 (LIB) 7-1
/PAGESIZE: option 7-13
combining libraries 7-12
command line format 7-5
consistency check 7-3, 7-13
cross-reference listing 7-12
LlB.EXE 7-2
responding to prompts 7-2
response fi Ie 7-8
setting page size 7-13
IBM Linker/2 8-1
IBM PC Assembler Language B-4
IBMBIO.COM 2-3
IBMDOS.COM 2-3
ignore response A-4
ignoring default library
names 8-23
index register B-5
initialization request 11-11
initializing a device driver 11-2
input bit, standard 11-6
Input command 10-23
Input Status, Check Standard B-23
input/output request 11-20
Input, Auxiliary B-15
installed state, get A-12
installing device drivers 11-2
installing the handler A-17
instruction pointer 8-5
internal stack B-6
interrupt flag 10-36

X·12

interrupt routines 11-7
build BPB request 11-16
character input/output flush
request 11-24
character input/output status
requests 11-23
command code value 11-9
generic 10Cti request 11-27
get logical device request 11-28
initialization request 11-11
input/output request 11-20
media check request 11-13
media descriptor byte 11-14
nondestructive input
request 11-22
open or close request 11-25
removable media request 11-25
request data structures 11-9
request header 11-7
set logical device request 11-28
interrupt vector
change contents of 6-13
definition of 6-13
Interrupt Vector, Get B-68
Interrupt Vector, Set 8-50
interrupt 21 H, issuing B-3
interrupt, setting the overlay 8-26
interrupts, DOS 4.00
absolute disk read/write (INT
25H/26H) A-7
critical error handler vector (INT
24H) A-3
Ctrl-Break exit address (INT
23H) A-2
function request (INT 21H) A-1
multiplex (INT 2FH) A-10
program terminate (INT
20H) A-1
terminate address (INT
22H) A-2
terminate but stay resident (INT
27H) A-9
INT21 function call B-3

invalid responses A-5
10Cti (see I/O Control for Devices)
10Cti bit 11-5
10Cti request, generic 11-27
IP (instruction pointer) B-5
IRET (return-from-interrupt instruction) A-2

K
Keyboard Buffer and Invoke a Keyboard Function, Clear B-24
Keyboard Input, Buffered B-22

L
LAN (see local area network)
LIB (see IBM Library Manager/2)
LIB command line parameters 7-5
LlB.EXE 1-2, 7-2
LIB, starting 7-2
Libraries [.LlB]: (prompt) 8-3
libraries, ignore default 8-23
libraries, object code 7-1
library
consistency check 7-3, 7-13
error messages 7-15
listing, cross-reference 7-12
page size 7-13
response file 7-8
search path 8-4
task descriptions 7-4
library file, creating a 7-9
library file, modify a 7-10
library management task
add an object module 7-11
delete an object module 7-11
extract copy from module 7-11
remove an object module 7-12
replace a module 7-11
library manager error
messages 7-15
Library Name: (prompt) 7-2

LIM (see Lotus/Intel/Microsoft)
LIM specification D-1
line numbers, copying 8-21
LINK
/CPARMAXALLOC option 8-14
/DOSSEG option 8-15
/DSALLOCATE option 8-16
/EXEPACK option 8-17
/HELP option 8-18
/HIGH option 8-19
/INFORMATION option 8-20
/LiNENUMBERS option 8-21
/MAP option 8-22
/NODEFAULTLiBRARYSEARCH
option 8-23
/NOGROUPASSOCIATION
option 8-24
/NOIGNORECASE option 8-25
/OVERLAYINTERRUPT
option 8-26
/PAUSE option 8-27
/SEGMENTS options 8-29
/STACK option 8-30
CodeView option 8-13
command line input 8-6
compiler compatibility 8-24
controlling data loading 8-16
copying line numbers 8-21
creating a map file 8-22
displaying process phase 8-20
error messages 8-37
example of prompts session 8-5
group pseudo-op
instruction 8-35
ignoring default libraries 8-23
imposed limits 8-48
linking an application 8-1
list file, content of 8-3
long reference 8-36
map files 8-3
near segment-relative
reference 8-36
near self-relative
reference 8-36

X·13

LINK (continued)
ordering segments 8-15
overlays 8-32
packing executable files 8-17
parameter descriptions 8-6
program stack size 8-30
reserving paragraph
space 8-14
response file 8-8
run file loading 8-19
segment limit setting
option 8-29
short reference 8-36
starting the linker 8-1
temporary disk file 8-5
terminating LINK 8-2
uppercasellowercase
distinction 8-25
using linker options 8-11
LINK command options 8-11
LINK error messages 8-37
LINK options
/CODEVIEW 8-13
/CPARMAXALLOC 8-14
IDOSSEG 8-15
IDSALLOCATE 8-16
IEXEPACK 8-17
IHELP 8-18
IHIGH 8-19
/INFORMATION 8-20
ILiNENUM8ERS 8-21
IMAP 8-22
INODEFAULTLl8RARYSEARCH
option 8-23
INOGROUPASSOCIATION 8-24
INOIGNORECASE 8-25
IOVERLAYINTERRUPT 8-26
IPAUSE 8-27
ISEGMENTS 8-29
ISTACK 8-30
public symbols list 8-3
LINK parameters. specifying 8-6
LINK references 8-35

X-14

LlNK.EXE 1-2.8-1
LINK-time information 8-20
LINK. starting 8-1
linker limits 8-48
linker list file 8-3
linking a program 8-1
List Entry. Get Redirection 8-124
List File [NUL.MAP]: (prompt) 8-3
list file. content of 8-3
List File: (prompt) 7-5
Load command 10-24
Load or Execute a Program
(EXEC) 8-101
load time. identify program at 6-4
loading a subprogram 6-7
loading an overlay 6-10
loading data using DE8UG 10-25
local area network (LAN) 3-8
local device. handle is C-10
local or remote device C-9
location of files on disk 2-2
lock conflicts C-11
Lock/Unlock File Access 8-118
logical device function call,
get/set 11-28
logical drive check C-27
logical record size 4-3
logical sector numbers (LSN) A-8
long (LINK reference) 8-36
Lotus/lntellMicrosoft (LIM) 0-1
lowercase/upper,fase
distinction 8-25
LSN (see logical sector numbers)

M
Machine Name, Get 8-121
map command, EMS 10-50
map file 8-31
map file, copy line numbers
to 8-21
map file, creating a 8-3
MAXALLOC field 8-14

media
check request 11-13
descriptor byte 11-14
media >32M8 A-7
media determination,
removable C-8
media warning, removable A-9
MediaType field C-21
memory
map address 6-2
overlay 6-10
paragraph form 6-1
program segment 6-4
reducing memory 6-2
memory blocks 6-1
Memory 810cks (SET8LOCK),
Modify Allocated 8-100
memory buffer (disk transfer
area) 4-5
memory map address 6-2
communication area 6-2
memory supported by DOS
4.00 0-1
Memory, Allocate 8-98
Memory, Free Allocated 8-99
merging libraries 7-12
messages, library manager
error 7-15
mode
compatibility 8-81
denynone 8-83
DenyRead 8-83
DenyRead/Write 8-82
DenyWrite 8-82
matrix of modes 8-83
open 8-79
sharing 8-79
Mode (CHMOD), Change File 8-92
Modify Allocated Memory 810cks
(SET8LOCK) 8-100
module, object
adding a module 7-11
copying a module 7-11
deleting a module 7-11

module, object (continued)
removing a module 7-12
replacing a module 7-11
Move command 10-27
Move File Read Write Pointer
(LSEEK) 8-90
multiplex (INT 2FH) A-10
APPEND A-13
function codes A-11
install a handler A-17
print error codes A-11

N
NA flag clear condition 10-36
name a file 3-1
Name command 10-29
name/unit field 11-6
Name, Get Machine 8-121
NAME = parameter 6-7
National Language Support
(NLS) 3-8
NC flag set condition 10-36
NEAR prefix, DE8UG 10-7
near segment-relative (LINK reference) 8-36
near self-relative (LINK
reference) 8-36
network path 3-8
network redirection 8-125
new.lib 7-10
NewName string 8-111
next device header 11-4
Next Entry, Search for 8-32
Next Matching File (FIND NEXT),
Find 8~109
NG flag set condition 10-36
NLS (see National Language
Support)
NLSFUNC DOS extension 8-133
nondestructive input request 11-22
NUL device 11-6
NUL.LST 7-5

X-15

numbering convention,
register 8-6
NumberOfCylinders field C-21
NV flag clear condition 10-36
NZ flag clear condition 10-36

object files 7-1
object module
adding a module 7-11
copying a module 7-11
deleting a module 7-11
removing a module 7-12
replacing a module 7-11
Object Modules [.08J]:
(prompt) 8-2
Open a File 8-78
Open a File, matrix of 8-83
OPEN call 11-25
Open File 8-27
open mode 8-79
Open/Create, Extended 8-138
opened file control block 4-1
Operations: (prompt) 7-3
symbols used at operations
prompt 7-4
task descriptions 7-4
options, LINK help 8-18
options, table of LINK 8-11
order of segments 8-33
ordering segments 8-15
output bit, standard 11-6
Output command 10-31
Output library: (prompt) 7-5
output/input request 11-20
Output, Auxiliary 8-16
Output, Display 8-14
Output, Printer 8-17
OV flag set condition 10-36
overflow flag 10-36
overlay interrupt, setting the 8-26
overlay restrictions 8-32

X-16

overlay, loading an 6-10
overlays created by LINK 8-32

p
packing executable files 8-17
page size, library 7-13
paragraph space option 8-14
paragraphs of memory 6-1
parameter block to
subprogram 6-7
parameter block, field in C-19
parameters specified to
EXE281N 9-2
parameters specified to LINK 8-6
parity flag 10-36
Parse Filename 8-56
parsing 4-7
path, library search 8-4
path, network 3-8
pausing to change disks 8-27
PE flag set condition 10-36
physical location of files 2-2
PL flag clear condition 10-36
PO flag clear condition 10-36
pOinter to next device header
field 11-4
pOinter to strategy/interrupt routines 11-6
pointers, list of 8-5
Prefix Address, Get Program
Segment 8-131
preserving
lowercase/uppercase 8-25
print error codes A-11
print failures A-13
print, resident part of A-11
Printer Output 8-17
Printer Setup, Get 8-123
Printer Setup, Set 8-122
problem diagnosis, library 7-15
Proceed command 10-32
Process (EXIT), Terminate a 8-105

process phase, displaying 8-20
processor, calling a
command 6-10
producing a public symbol
map 8-22
Program (EXEC), Load or Execute
a B-101
program (INT 20H), terminate A-1
program activity
control-break routine 6-12
identifying a program at load
time 6-4
loading an overlay 6-10
requesting interrupt
vectors 6-13
responding to errors 6-11
terminating programs 6-8
program code fragments B-4
program remain resident A-9
program segment 6-4
program segment prefix 6-4,6-5
Program Segment Prefix Address,
Get B-131
Program Segment, Create
New B-51
program stack size setting
option 8-30
Program Terminate B-12
prompt
(DEBUG prompt) hyphen
(-) 10-1
Definition File [.def]: 8-4
Libraries [.lib]: 8-3
Library Name: 7-2
List File [nul.map]: 8-3
List File: 7-5
Object Modules [.OBJ]: 8-2
Operations: 7-3
Output library: 7-5
Run File [filename.exe]: 8-2
prompt examples, LINK 8-5
pseudo-up instructions 8-33
public symbols list 8-3, 8-22

Q
Quit command

10-33

R
Random Block Read B-52
Random Block Write B-54
Random Read B-44
Random Write B-46
re-displaying Load
command 10-25
Read from a Fi Ie or Device B-86
read track on a logical device C-24
Read Write Pointer (LSEEK),
Move 8-90
read/write (INT 25H/26H), absolute
disk A-7
Read, Random 8-44
Read, Random 810ck 8-52
Read, Sequential B-35
real time clock 11-29
Record Field, Set Relative B-49
record number 4-4
Redirect Device 8-126
Redirection List Entry, Get B-124
Redirection, Cancel B-129
redirection, network B-125
reduce allocated memory 6-2
reference fix by LINK 8-35
references
long 8-36
near segment-relative 8-36
near self-relative 8-36
short 8-36
Register command 10-34
changing a flag 10-36
list of flag settings 10-36
registers, display 10-35
registers, DOS 4.00
accumulator register B-4
AH 8-4
AL 8-4
AX 8-4
base 8-4

X-17

registers, DOS 4.00 (continued)
base pOinter 8-5
8H 8-4
8L 8-4
8P (base pointer) 8-5
8X 8-4
CH 8-5
CL 13-5
code segment 8-5
count register 8-5
CS 8-5
CX 8-5
data register 8-5
data segment 8-5
destination index 8-6
DH 8-5
01 8-5
DL 8-5
OS 8-5
OX 8-5
ES 8-5
extra segment 8-5
flags 8-5
index registers 8-5
instruction pointer 8-5
internal stack 8-6
IP (instruction pointer) 8-5
numbering convention 8-6
pOinters, list of 8-5
segment register 8-5
SI 8-6
source index 8-6
SP (stack pointer) 8-5
SS 8-5
stack pOinter 8-5
stack segment 8-5
relocatable/executable file 8-1
remain resident, program A-9
remote device, handle is C-10
remote or local device C-9
removable media
notifyi ng a utility 11-25
open/close bit 11-5

X-18

removable media
determination C-8
removable media warning A-9
remove a module 7-12
Remove Subdirectory
(RMDIR) 8-75
Rename a File 8-111
Rename File 8-38
reopen a file (matrix) 8-83
replace a module 7-11
request header 11-7
busy bit 11-8
command code field 11-8
done bit 11-8
error codes, status word 11-9
status field 11-8
unit code field 11-8
reserved fields in file control
block 4-1
reserving paragraph space 8-14
Reset, Disk 8-25
resident (INT 27H), terminate but
stay A-9
resident part of print A-11
responding to errors 8-6
response file, library manager 7-8
response file, process a 8-8
response, ignore A-4
responses, invalid A-5
restrictions on overlays 8-32
Return Code of a Subprocess
(WAIT), Get 8-106
return from interrupt (IRET) 6-12
retu rn-from-i nterru pt i nstructi on
(IRET) A-2
ROM 810S routine 8-15
ROM communication area 6-2
root directory 2-3
routines, pOinter to
strategylinterrupt 11-6
Run file [filename.EXE]:
(prompt) 8-2
run file loading 8-19

S
S/ format option 2-3
save area, parameter 6-6
save mode of device driver 11-6
Search command 10-38
Search for First Entry 8-30
Search for Next Entry 8-32
search in disk directory 4-5
sector sequence on formatted
disk 2-1
sector size 2-1
sectors
formula for number of 2-2
numbering sequentially A-8
Write command, maximum
for 10-45
segment group error 8-35
segment limit setting option 8-29
Segment Prefix Address, Get
Program 8-131
segment prefix, program 6-5
segment register 8-5
segment, align types of 8-33
Segment, Create New
Program 8-51
segments, ordering 8-15
Select Disk 8-26
separators, filename 8-57
Sequential Read 8-35
Sequential Write 8-36
set condition of flag 10-36
Set Date 8-59
set device information C-3
set device parameters C-19
Set Disk Transfer Address 8-41
Set Handle Count 8-136
set logical device function
call 11-28
set logical drive C-28
Set Printer Setup 8-122
Set Relative Record Field 8-49
Set Time 8-61

Set/Reset Verify Switch 8-62
setting stack size 8-30
setting the library page size 7-13
Setting, Get Verify 8-110
sharing and lock conflicts C-11
sharing mode 8-79
short (LINK reference) 8-36
SI register 8-6
sign flag 10-36
single block device driver 11-2
Size, Fi Ie 8-48
size, logical record 4-3
source index 8-6
SP (stack pOinter) 8-5
SP register 6-6
Special Functions field C-19
SS register 8-5
stack
pOinter 8-5
segment 8-5
size of program 8-30
stack, internal 8-6
stack, user A-3
standard device file handle 3-3
standard input bit 11-6
standard output bit 11-6
starting a device driver 11-2
starting DE8UG 10-1
static envi ronment 6-6
status A-13
status command, EMS 10-51
status field 11-8
status function call
parameter 11-23
status word error codes 11-9
status, end of A-13
STDAUX 3-3
STDERR 3-3
STDIN 3-3
STDOUT 3-3
STDPRN 3-3
stop briefly to change disk 8-27
strategy routine
definition of 11-6

X-19

strategy routine (continued)
save mode 11-6
String, Display 8-21
string, NewName 8-111
string, subprogram
environment 6-7
subdirectories, location of 2-4
Subdirectory (MKDIR),
Create 8-74
Subdirectory (RMDIR),
Remove 8-75
subdirectory entries 3-4
subfunction calls for code page
switching C-12
submit file A-12
Subprocess (WAIT), Get a Return
Code of a 8-106
subprogram
command line 6-8
environment string 6-7
executing a subprogram 6-7
loading an overlay 6-10
passing a parameter block 6-7
terminating a subprogram 6-8
support of expanded memory 0-1
Switch, Set/Reset Verify 8-62
symbols used at Operations
prompt 7-4
system date and time 6-13
System Value, Get/Set 8-66

T
task descriptions at Operations
prompt 7-4
temporary disk file 8-5
terminate (INT 20H), program A-1
Terminate a Process (EXIT) 8-105
terminate address (INT 22H) A-2
terminate but stay resident (INT
27H) A-9
Terminate Process and Remain
Resident 8-65

X-20

Terminate, Program 8-12
terminating the input queue 11-24
terminators, filename 8-57
TEST.08J 7-7
time in a directory structure 3-6
Time, Get 8-60
Time, Get/Set File's Date
and 8-112
Time, Set 8-61
time, system 6-13
Trace command 10-40
track, format/verify a C-24
TrackLayout field C-22
Transfer Address, Set Disk 8-41
transfer area, disk 4-5

U
Unassemble command 10-42
unit code field 11-8
unit field 11-6
unopened file control block 4-1
UP flag clear condition 10-36
uppercasellowercase
distinction 8-25
user stack A-3
using a response file 8-8
using DOS 4.00 function calls 8-3
utilities diskette 1-2
utility format, EXE28IN.EXE 9-1
utility, DE8UG.COM 10-1
utility, DISKCOMP 10-1

V
values in a command code 11-8
VDISK.ASM 1-2
vector (INT 24H), critical error
handler A-3
vector table 6-2
Vector, Get Interrupt 8-68
Vector, Set Interrupt 8-50
vectors, requesting and specifying
the interrupt 6-13

verify a track C-24
Verify Setting, Get 8-110
Verify Switch, Set/Reset 8-62
viewing the options list 8-18

W
word fields in device header 11-4
wraparound 11-20
Write command 10-45
Write to a Fi Ie or Device 8-87
write track on a logical
device C-24
Write, Random 8-46
Write, Random 810ck 8-54
Write, Sequential 8-36

Z
zero flag 10-36
ZR flag set condition

10-36

Numerics
32M8, media greater than A-7
8086/8088 code rules 10-6

X-21

X-22

Continued from inside front cover.
SUCH WARRANTIES ARE IN LIEU OF
ALL OTHER WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE.
Some states do not allow the exclusion
of implied warranties, so the above
exclusion may not apply to you.
LIMITATION OF REMEDIES
IBM's entire liability and your exclusive
remedy shall be as follows:
1) IBM will provide the warranty
described in IBM's Statement of
Limited Warranty. If IBM does not
replace defective media or, if applicable, make the Program operate as
warranted or replace the Program
with a functionally equivalent Program, all as warranted, you may
terminate your license and your
money will be refunded upon the
return of all of your copies of the
Program.
2) For any claim arising out of IBM's
limited warranty, or for any other
claim whatsoever related to the
subject matter of this Agreement,
IBM's liability for actual damages,
regardless of the form of action,
shall be limited to the greater of
$5,000 or the money paid to IBM, its
Authorized Dealer or its approved
supplier for the license for the
Program that caused the damages
or that is the subject matter of, or is
directly related to, the cause of
action. This limitation will not apply
to claims for personal injury or
damages to real or tangible personal
property caused by IBM's negligence.

In no event will IBM be liable for any
lost profits, lost savings, or any
incidental damages or other consequential damages, even if I BM, its
Authorized Dealer or its approved
supplier has been advised of the
possibility of such damages, or for
any claim by you based on a third
party claim.
Some states do not allow the limitation
or exclusion of incidental or consequential damages so the above limitation or
exclusion may not apply to you.
GENERAL
You may terminate your license at any
time by destroying all your copies of the
Program or as otherwise described in
this Agreement.
IBM may terminate your license if you
fail to comply with the terms and conditions of this Agreement. Upon such
termination, you agree to destroy all your
copies of the Program.
Any attempt to sublicense, rent, lease or
assign, or, except as expressly provided
herein, to transfer any copy of the
Program is void.
You agree that you are responsible for
payment of any taxes, including personal
property taxes, resulting from this
Agreement.
No action, regardless of form, arising
out of this Agreement may be brought by
either party more than two years after
the cause of action has arisen except for
breach of the provisions in the Section
entitled "License" in which event four
years shall apply.
This Agreement will be construed under
the Uniform Commercial Code of the
State of New York

Z125-3301-024/87

--------- -----,-

-- --

15F0256

International Business Machines Corporation
IBM Program License Agreement
Warranty:
Media-three-month warranty
Program-three-month warranty
Program services:
Avail3/;>le after warranty-yes
Charges apply-no
Service expiration date:

8/31/89
No program services are
available after this date.

@IBM is a regi stered trademark of
International Business Machines
Corporation.

---- ---------_.-

Armonk, New York 10504

BEFORE OPENING THIS PACKAGE, YOU SHOULD CAREFULLY READ THE FOLLOWING
TERMS AND CONDITIONS. OPENING THIS PA'CKAGE INDICATES YOUR ACCEPTANCE
OF THESE TERMS AND CONDITIONS. IF YOU DO NOT AGREE WITH THEM, YOU
SHOULD PROMPTLY RETURN THE PACKAGE UNOPENED AND YOUR MONEY WILL
BE REFUNDED.
This is a license agreement and not an agreement for
sale. IBM owns, or has licensed from the owner, copyrights in the Program. You obtain no rights other than the
license granted you by this Agreement. Title to the
enclosed copy of the Program, and any copy made from
it, is retained by IBM . IBM licenses your use of the
Program in the United States and Puerto Rico. You
assume all responsibility for the selection of the Program
to achieve your intended results and for the installation
of, use of, and results obtained from , the Program.
The Section in the enclosed documentation entitled
"License Information" contains additional information
concerning the Program and any related Program
Services.
LICENSE
You may:
1) use the Program on only one machine at anyone time,
unless permission to use it on more than one machine
at anyone time is granted in the License Information
(Authorized Use);
2) make a copy of the Program for backup or modification purposes only in support of your Authorized
Use. However, Programs marked "Copy Protected "
limit copying;
3) modify the Program and / or merge it into another
program only in support of your Authorized Use; and
4) transfer possession of copies of the Prog ram to
another party by transferring this copy of the IBM
Program License Agreement, the License Information , and all other documentation along with at least
one complete, unaltered copy of the Program. You
must, at the same time, either transfer to such other
party or destroy all your other cop ies of the Program,
including modified copies or portions of the Program
merged into other programs. Such transfer of posses sion terminates your license from IBM. Such other
party shall be licensed, under the terms of this
Agreement, upon acceptance of this Agreement by its
initial use of the Program.
You shall reproduce and include the copyright notice(s)
on all such copies of the Program , in whole or in part.
You shall not:
1) use, copy, modify, merge, or transfer copies of the
Program except as provided in this Agreement;
2) reverse assemble or reverse compile the Program ;
and / or
3) sublicense, rent, lease, or assign the Program or any
copy thereof.
LIMITED WARRANTY
Warranty details and limitations are described in the
Statement of Limited Warranty which is available upon
request from IBM , its Authorized Dealer or its approved
supplier and is also contained in the License Information.IBM provides a three-month limited warranty on the
media for all Programs. For selected Programs, as
indicated on the outside of the package, a limited
warranty on the Program is available. The applicable
Warranty Period is measured from the date of delivery to
the original user as evidenced by a receipt.
Certain Programs, as indicated on the outside of the

package, are not warranted and are provided "AS IS."
SUCH WARRANTIES ARE IN LIEU OF ALL OTHER
WARRANTIES, EXPRESS OR IMPLIED, INCLUDING ,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
Some states do not allow the exclusion of implied
warranties, so the above exclusion may not apply to you.
LIMITATION OF REMEDIES
IBM's entire liability and your exclusive remedy shall be
as follows:
1) IBM will provide the warranty described in IBM's
Statement of Limited Warranty. If IBM does not replace
defective media or, if applicable, make the Program
operate as warranted or replace the Program with a
functionally equivalent Program, all as warranted , you
may terminate your license and your money will be
refunded upon the return of all of your copies of the
Program .
2) For any claim arising out of IBM 's limited warranty, or
for any other claim whatsoever related to the subject
matter of this Agreement, IBM's liability for actual
damages, regardless of the form of action , shall be
limited to the greater of $5,000 or the money paid to
IBM , its Authorized Dealer or its approved supplier for
the license for the Program that caused the damages
or that is the subject matter of, or is directly related to,
the cause of action . Th is limitation will not apply to
claims for personal injury or damages to real or
tangible personal property caused by IBM's negligence.
3) In no event will IBM be liable for any lost profits, lost
savings, or any incidental damages or other consequential damages, even if IBM , its Authorized
Dealer or its approved supplier has been advised of
the possibility of such damages, or for any claim by
you based on a third party claim.
Some states do not allow the limitation or exclusion of
incidental or consequential damages so the above
limitation or exclusion may not apply to you.
GENERAL
You may terminate your license at any time by destroying
all your copies of the Program or as otherwise described
in this Agreement.
IBM may terminate your license if you fail to comply
with the terms and conditions of this Agreement. Upon
such termination, you agree to destroy all you r copies of
the Program.
Any attempt to sublicense, rent, lease or assign, or,
except as expressly provided herein, to transfer any
copy of the Program is void.
You agree that you are responsible for payment of any
taxes, including personal property taxes, resulting from
this Agreement.
No action, regardless of form , arising out of this
Agreement may be brought by either party more than
two years after the cause of action has arisen except for
breach of the provisions in the Section entitled " License"
in which event four years shall apply.
This Agreement will be construed under the Uniform
Commercial Code of the State of New York.

Z12S-3301-024 /87

6280254

*9062802540001*

Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.6 Linearized : No Create Date : 2013:06:11 13:54:58-08:00 Modify Date : 2013:06:11 14:06:48-07:00 XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37 Metadata Date : 2013:06:11 14:06:48-07:00 Producer : Adobe Acrobat 9.55 Paper Capture Plug-in Format : application/pdf Document ID : uuid:1439b1f7-a660-48b0-ab52-98bdca9e7076 Instance ID : uuid:86d9a6f6-3158-4b55-ad3a-1fd64994c351 Page Layout : SinglePage Page Mode : UseNone Page Count : 446
EXIF Metadata provided by EXIF.tools

15F0256_DOS_4.0_Technical_Reference_Jul88 15F0256 DOS 4.0 Technical Reference Jul88

15F0256_DOS_4.0_Technical_Reference_Jul88 15F0256_DOS_4.0_Technical_Reference_Jul88

Navigation menu

Versions of this User Manual:

Views

Navigation