1502346 dos 2.10 technical reference sep83

8/13/2019 1502346 DOS 2.10 Technical Reference Sep83

http://slidepdf.com/reader/full/1502346-dos-210-technical-reference-sep83 1/178



_

Personal omputeromputer Language

Series

Diskperating

SystemTechnical Reference

by Microsoft Corp.



First Edition (September 1983)Version 2.10

International Business Machines Corporation provides this manualas is without warranty of any kind, either express or implied,

including, but not limited to the implied warranties ofmerchantability and fitness for a particular purpose. IBM may makeimprovements and or change n the product( s) and or the program( s)described in this manual at any time and without notice.

Products are not stocked at the address below. Requests for copiesof this product and for technical information about the systemshould be made to your authorized IBM Personal Computer Dealer.

This publication could contain technical inaccuracies ortypographical errors. Changes are periodically made to theinformation herein; these changes will be incorporated in neweditions of this publication.

A Reader's Comment Form s provided at the back ofthispublication. If this form has been removed, address commentsto: IBM Corp., Personal Computer, P.O. Box 1328-W, BocaRaton, Florida 33432. IBM may use or distribute any of theinformation you supply in any way it believes appropriate withoutincurring any obligations whatever.

© Copyright International Business Machines Corp. 1983



Preface

Read This irst

This technical reference manual covers topics for themore experienced OS users system programmersand those who will be developing their ownapplications. Information s also provided about yourfixed disk and some of the other new features of

OS 2.10.

Organization o This Manual

This manual has 9 chapters.

Chapter 1 contains general technical information.

Chapter 2 contains detailed information about usingextended screen and keyboard functions.

Chapter 3 contains detailed information about devicedrivers.

Chapter 4 describes allocation of space on a disk.

Chapter 5 describes the system interrupts and functioncalls.

Chapter 6 describes control blocks and work areasincluding a Memory Map Program Segment and FileControl Block.

iii



iv

Chapter 7 explains how to execute commands fromwithin an application

Chapter 8 contains technical information about DOS

support of fixed disks

Chapter 9 contains detailed information about EXE

file structure

Chapter 10 contains information about DOS memorymanagement



ontents

Chapter 1. DOS Technical Information 1 1

DOS Structure 1-3DOS Initialization 1-4The Command Processor 1 5

Available DOS Functions 1-6File Management Notes 1-6The Disk Transfer Area DT A 1 7Error Trapping 1-8

Chapter 2. Using Extended Screen andKeyboard Control 2 1

Introduction 2-3Cursor Control 2-4

Cursor Position 2-4Cursor Up 2-4Cursor Down 2-5Cursor Forward 2-5Cursor Backward 2-5Horizontal and Vertical Position 2-6Device Status Report 2-6Cursor Position Report 2-6Save Cursor Position 2-7

Restore Cursor Position 2-7Erasing 2-8

Erase in Display 2-8Erase in Line 2-8

Mode of Operation 2-9Set Graphics Rendition 2-9Set Mode 2-10Reset Mode 2-10

Keyboard Key Reassignment 2-11



Chapter 3. Installable Device Drivers 3 1

Introduction 3 3Device Driver Format 3 4

Types of Devices 3 4Device Header 3 6

Creating a Device Driver 3 9Installation of Device Drivers 3 10Request Header 3 11

Unit Code 3 11Command Code 3 12Status Word 3 13Function Call Parameters 3 16MEDI Descriptor Byte 3 21

The CLOCKS Device 3 26Sample Device Driver 3 27

Chapter 4. DOS Disk Allocation 4 1DOS Disk Directory 4 4DOS File Allocation Table 4 8How to Use the File Allocation Table 4 10

Chapter 5. DOS Interrupts and FunctionCalls 5 1

Interrupts 5 3Function Calls 5 13Invoking DOS Functions 5 16

Chapter 6. DOS Control Blocks and

Work Areas 6 1DOS Memory Map 6 3DOS Program Segment 6 5Program Segment Prefix 6 9File Control Block 6 11

Chapter 7. Executing Commandsfrom Within an pplication 7 1

vi



Chapter 8. Fixed Disk Information 8 1

Fixed Disk Architecture 8 3

System Initialization 8 4Boot Record/Partition Table 8 6Technical Information 8 8

Chapter 9. EXE File Structureand Loading 9 1

Chapter 10. DOS Memory Management 10 1

I n d e x . X I

vii



v



hapter 1 OS Technical ReferenceInformation

ontents

DOS Structure 1-3DOS Initialization 1-4The Command Processor 1 5

AvailableDOS

Functions 1-6File Management Notes 1-6The Disk Transfer Area DT A 1-7Error Trapping 1-8

1 1



1 2



This book and Appendix D of the IBM isk peratingSystem Reference are intended to supply technicallyoriented users with information about the structure,facilities, and program interfaces of DOS t is assumedthat the reader is familiar with the 8088 architecture,

interrupt mechanism, and instruction set.

OS tructure

DOS consists of the following four components:

1. The boot record resides on track 0, sector 1, side 0of every disk formatted by the FORMAT

command. t is put on all disks in order to producean error message if you try to start up the systemwith a non-DOS diskette in drive A. For fixeddisks, it resides on the first sector sector 1 head0) of the first cylinder of the DOS partition.

2. The Read-Only Memory ROM) BIOS interfacemodule file IBMBIO.COM) provides a low-levelinterface to the ROM BIOS device routines.

3. The DOS program itself file IBMDOS.COM)provides a high-level interface for user programs. t

consists of file management routines, datablocking/deblocking for the disk routines, and a

variety of built-in functions easily accessible byuser programs. Refer to Chapter 5.)

When these function routines are invoked by auser program, they accept high-level informationvia register and control block contents, then fordevice operations) translate the requirement intoone or more calls to IBMBIO to complete therequest.

4. The command processor, COMMAND COM

1-3



OS nitialization

1-4

When the system is started either System Reset orpower ON with the DOS diskette in drive A), the bootrecord s read into memory and given control. It checks

the directory to assure that the first two files listed areIBMBIO.COM and IBMDOS.COM, in that order. Anerror message s issued if not.) These two files are thenread into memory. IBMBIO.COM must be the first filein the directory, and its sectors must be contiguous.)

The initialization code in IBMBIO.COM determinesequipment status, resets the disk system, initializes theattached devices, causes device drivers to be loaded,and sets the low-numbered interrupt vectors. t thenrelocates IBMDOS.COM downward and calls the firstbyte of DOS.

As in IBMBIO.COM, offset 0 in DOS contains ajumpto its initialization code, which will later be overlaid by

a data area and the command processor. DOSinitializes its internal working tables, initializes interruptvectors for interrupts hex 20 through hex 27 and buildsa Program Segment Prefix see Chapter 6) forCOMMAND COM at the lowest available segment,then returns to IBMBIO. COM.

The last remaining task of initialization s forIBMBIO.COM to load COMMAND COM at thelocation set up by DOS initialization. IBMBIO.COMthen passes control to the first byte of COMMAND



The ommand Processor

The command processor supplied with DOS (fileCOMMAND. COM) consists of four distinctly separateparts:

• A resident portion resides in memory immediatelyfollowing IBMDOS.COM and its data area. Thisportion contains routines to process interrupt typeshex 22 (terminate address), hex 23(CTRL-BREAK handler), and hex 24 (criticalerror handling), as well as a routine to reload thetransient portion if needed. (When a programterminates, a checksum methodology determines ifthe program had caused the transient portion to beoverlaid. f so, it s reloaded.) Note that allstandard DOS error handling is done within thisportion of COMMAND. This includes displayingerror messages and interpreting the reply of Abort,Retry, or Ignore. (See message Disk error reading

drive x in Appendix A of the isk peratingSystem Reference manual.)

• An initialization portion follows the residentportion and s given control during startup. Thissection contains the AUTOEXEC file processorsetup routine. The initialization portion determinesthe segment address at which programs can beloaded. t s overlaid by the first programCOMMAND loads because it s no longer needed.

• A transient portion is loaded at the high end ofmemory. This s (portion 3) the commandprocessor itself, containing all of the internalcommand processors, the batch file processor, and(portion 4) a routine to load and execute externalcommands (files with filename extensions of.COM or .EXE). This loader is at the highestend of memory, and is invoked by the EXECfunction call to load programs.

1-5



Portion 3 of COMMAND produces the systemprompt (such as A » reads the command from thekeyboard (or batch file) and causes it to beexecuted. For external commands, it builds acommand line and issues an E XEC function call

to load and transfer control to the program.

Chapter 6 contains detailed information describing theconditions in effect when a program is given control byEXEC.

vailable OS FunctionsDOS provides a significant number of functions to userprograms, all available through issuance of a set of

interrupt codes. There are routines for keyboard input(with and without echo and Ctrl-Break detection),console and printer output, constructing file controlblocks, memory management, date and time functions,and a variety of disk, directory, and file handlingfunctions. See Chapter 5 DO S Interrupts andFunction Calls for detailed information.

File Management Notes

1 6

Through the INT 2 (function call) mechanism, DOS

provides methods to create, read, write, rename, anderase files. Files are not necessarily written sequentiallyon disk-space is allocated as it is needed, and the firstlocation available on the disk is allocated as the nextlocation for a file being written. Therefore, ifconsiderable file creation and erasure activity has takenplace, newly created files will probably ot be written insequential sectors.

However, due to the mapping (chaining) of file spacevia the File Allocation Table, and the function callsavailable, any file can be used in either a sequential or

random manner.



When using the extended file management functioncalls, you specify a buffer address when you issue theread or write call. There is no need to set a DT Aaddress.

rror Trapping

1 8

DOS provides a method by which a program canreceive control whenever a disk or device read/writeerror occurs, or when a bad memory image of the fileallocation table is detected. When these events occur,DOS executes an INT hex 24 to pass control to the

error handler. The default error handler resides inCOMMAND. COM, but any program can establish itsown by setting the INT hex 24 vector to point to thenew error handler. DOS provides error information viathe registers and provides Abort, Retry, or Ignoresupport via return codes. (Refer to Chapter 5, DOS

Interrupts and Function Calls .)



Chapter 2 Using ExtendedScreen and KeyboardControl

Contents

Introduction 2 3

ursor ontrol 2 4Cursor Position 2 4Cursor Up 2 4Cursor Down 2 5Cursor Forward 2 5Cursor Backward 2 5Horizontal and Vertical Position 2 6Device Status Report 2 6Cursor Position Report 2 6Save Cursor Position 2 7Restore Cursor Position 2 7

Erasing 2 8Erase in Display 2 8Erase in Line 2 8

Mode of Operation 2 9Set Graphics Rendition 2 9Set Mode 2 10Reset Mode 2 10

Keyboard Key Reassignment 2 11

2 1



ntroduction

With DOS Version 2.10 you can issue special charactersequences from within your program that can be used tocontrol screen cursor positioning. You can also reassignthe meaning of any key in the keyboard.

Notes:

1 The control sequences defined below are validwhen issued through any DOS function calls, thatcan write to the standard output device. Thesecontrol sequences require the presence of theextended screen and keyboard control devicedriver. This can be accomplished by placing thecommand:

DEVICE=ANSI SYS

in your CONFIG. SYS configuration) file.Note that the size of DOS in memory will beincreased by the size of the ANSI. SYSprogram.

2. The default value is used when no explicitvalue, or a value of zero, is speCified.

3. # - Numeric Parameter. A decimal numberspecified with ASCII characters.

4. In the control sequences described below,ESC

is the 1 byte code forESC

hex IB),ot the three characters ESC. For

example, ESC [2;10H could be created underDEBUG as follows:

e2 8 [2;10H

2-3



ursor ontrol

ursor Position

UP unction

ES [ ; H Moves the cursor to the position specified by theparameters. The first parameter specifies theline number and the second parameter specifiesthe column number. The default value is one. f

no parameter is given, the cursor is moved to thehome position.

ursor p

UD unction

ES [ A Moves the cursor up one line without changingcolumns. The value of determines the numberof lines moved. The default value for is one.

This sequence is ignored if the cursor is alreadyon the top line.

2 4



Cursor own

CUD Function

ES [ 8 Moves the cursor down one line withoutchanging columns. he value of determinesthe number of lines moved. he default valuefor is one. he sequence is ignored i f thecursor is already on the bottom line.

Cursor Forward

CUF Function

ES [ C Moves the cursor forward one column withoutchanging lines. The value of determines thenumber of columns moved. he default value

for is one. This sequence is ignoredif

thecursor is already in the rightmost column.

Cursor ackward

CU Function

ES [ 0 Moves the cursor back one column withoutchanging lines. he value of P n determines thenumber of columns moved. he default valuefor P n is one. This sequence is ignored if thecursor is already in the leftmost column.

2-5



Horizontal and Vertical Position

HVP Function

ES [ ; 1 Moves the cursor to the position specified by theparameters. The first parameter specifies theline number and the second parameter specifiesthe column number. The default value s one. f

no parameter s given, the cursor is moved to thehome position same as CUP).

Device Status Report

D S R Function

ES [6n The console driver will output a PR sequenceon receipt of DSR see below).

Cursor Position Report

PR Function

ES [ ; R The PR sequence reports the current cursor

position through the standard input device. Thefirst parameter specifies the current line and thesecond parameter specifies the current column.

2 6



S ave Cursor Position

S P Function

ES s The current cursor position s saved. This cursorposition can be restored with the R P sequence.

Restore Cursor Position

R P Function

ES [u Restores the cursor to the value it had when theconsole driver received the SCP sequence.

2 7



Erasing

Erase in isplay

E Function

ES [ J Erases all of the screen and the cursor goes tothe home position

Erase in Line

L Function

ES k Erases from the cursor to the end of the line andincludes the cursor position

2 8



Mode o Operation

Set raphics Rendition

SGR unction

ES [ ; ; m Sets the character attribute specified by theparameter s). All following characters will havethe attribute according to the parameter s) untilthe next occurrence of SG R

Parameter Meaning0 All attributes Off normal

white on black)1 Bold On high intensity)4 Underscore On IBM

Monochrome Display only)5 Blink On7 Reverse video On8 Cancelled On invisible)30 Black foreground31 Red foreground

32 Green foreground33 Yellow foreground34 Blue foreground35 Magenta foreground36 Cyan foreground37 White foreground40 Black background41 Red background42 Green background43 Yellow background44 Blue background45 Magenta background46 Cyan background47 White background

2 9



Set Mode

SM Function

ESC [= h Invokes the screen width or type specified byor ESC [=h the parameter.or ESC [=Ohor ESC [?7h Parameter Meaning

0 40x25 black and white40x25 color

2 80x25 black and white3 80x25 color4 320x200 color5 320x200 black and white6 640x200 black and white7 wrap at end of line

(typing past end-of-line resultsin new line)

Reset Mode

RM Function

ESC [= 1 Parameters are the same as SM (Set Mode)

or ESC [=1 except that parameter 7 will reset wrap ator ESC [= 1 end-of-line mode (characters past end-of-line areor ESC [?71 thrown away).

2-10



Keyboard Key Reassignment

The controlsequence is Function

ESC [#;#; .. #p The first ASCII code in the controlor ESC [ string ;p sequence defines which code is beingor ESC mapped. The remaining numbers define

[#; s tr ing ;#; the sequence of ASCII codes generated#; string ;#p when this key is intercepted. However, if

or any other the first code in the sequence is zero

combinationof NUL)

then the first and second codestrings and make up an extended ASCIIdecimal numbers re-definition. See Chapter 5. The IBM

Personal Computer B SIC manual hasa list of all the ASCII and extendedASCII codes).

Here are some examples:

1 Reassign the Q and q key to the A and a key andthe other way as well):

ESC [65;81 A becomes QESC [97; 113p a becomes qESC [81 P;65p Q becomes AESC [113;97p q becomes a

2. Reassign the FlO key to a DIR command followedby a carriage return:

ESC [O;68; dir ;13p

The 0;68is

the extendedASCII

code for theFlO

key. 13 decimal is a carriage return.

2 11



3. The following assembly language programreassigns the FlO key to a IR B: commandfollowed by a carriage return.

TITLE S ~ T A N S I . A S M- SET FID TOSTRINGFORANSI.SYSCSEG SEGMENTP R PUBLIC 'CODE'

ASSUMEC S : C S E G D S : ~ § E G

ORGDOS LABEL

ORGENTPT: JMPSTRINq DB

STRSIZ EQUH NDLEEQU

5DHF RlODHSHORT START17,'[Di&8i SDIR B: i13p'

S-STRING

INT 11H RET F R

iREDEFINEF1D KEY

;LENGTHOF BOVEMESSAGEiPRE-DEFINEDFILE HANDLEFOR STANDARDOUTPUT

VECTORTODOSC LLROUTINEDOSVECTOR LABELDWORDDOSOFF OW DOSDOSSEG OW

START PROC NE R

MOVMOV

AX,CSDOSSEG,AX

; OFFSET; SEGMENT(TO BE FILLED)

;FINDWHERETHIS CODEIS;SET VECTORACCORDINGLY

i <th is is done so this code becomes self-relocatable, suitable for .com file)

NOV BX,HANDLE iSTANDARD OUTPUTDEVICEMOV CX,STRSIZ iGET SIZE OF TEXT TO BESENTMOV DX,OFFSETSTRING iPASS OFFSETOF STRINGTO BESENTMOV AH,4DH iFUNCTION= WRITETO DEVICECAll DOSVECTOR iCALL DOSRET iRETURNTODOS

START ENDPCSEG ENDS

END ENTPT

2-12



Chapter 3 Installable evice Drivers

Contents

Introduction 3-3

Device Driver Format 3-4Types of Devices 3-4

Character Devices 3 5

Block Devices 3 5Device Header 3-6

Next Device Header Field 3-6Attribute Field 3 7Strategy and Interrupt Routines 3-8N arne Field 3-8

Creating a Device Driver 3-9

Installation of Device Drivers 3-10

Request Header 3 11

Unit Code 3 11

Command Code 3-12StatusWord 3-13Function Call Parameters 3-16

INIT 3-17MEDI CHECK 3-18BUILDBPB

BIOS Parameter Block) 3-18MEDI Descriptor Byte 3 21

INPUT or OUTPUT 3-22Non Destructive Input No Wait 3-24

STATUS 3-24FLUSH 3-25

The CLOCKS Device 3-26

Sample Device Driver 3-27

3 1



3 2



ntroduction

The DOS Version 2 10 device interface links thedevices together in a chain This allows new devicedrivers for optional devices to be added to DOS

3 3



evice river Format

A device driver is a .COM file with all of the code in itto implement the device. In addition it has a specialheader at the front of it that identifies it as a device,defines the strategy and interrupt entry points, anddefines various attributes of the device.

Note: For device drivers, the .COM file must

not use the ORG lOOH. Because it does not usethe program segment prefix, the device driver s

simply loaded; therefore, the .COM file must havean orgin of zero ORG 0 or no ORG statement .

Types o evices

There are two basic types of devices:

• Character devices

• Block devices

3-4



Character Devices

These are devices that are designed to do character I/Oin a serial manner like CON, AUX, and PRN. Thesedevices have names like CON, AUX, CLOCK , and

you can open channels (handles or FCBs) to do inputand output to them.

Note: Because character devices have only onename, they can support only one device.

lock Devices

These devices are the fixed disk or diskette drives onthe system, they can do random I/O in pieces calledblocks (usually the physical sector size of the disk).These devices are not n med as the character devicesare, and cannot be opened directly. Instead they arem pped via the drive letters (A, B C, etc.). Blockdevices can have units within them. In this way, a singleblock driver can be responsible for one or more disk ordiskette drives. For example, block device driverALPHA can be responsible for drives A, B C and D.This means that ALPHA has four units defined andtherefore takes up four drive letters. The way the driveunits and drive letters correspond is determined by theposition of the driver in the chain of all drivers. For

example, if device driver ALPHA is the first blockdriver in the device chain, and it has defined four units,then those units will be A, B C and D. If BETA is thesecond block driver, and it defines three units, thenthose units will be E, F and G. DOS Version 2.10 isnot limited to 16 block device units as previous versionswere. The new limit is 63, but drives are assignedalphabetically through the collating sequence, so after

drive Z, the drive characters get a little strange (like< \ ».

3-5



evice Header

A device header is required at the beginning of a devicedriver. Here is what the Device Header looks like:

Description Definition

Pointer to next device header DWORD

Attribute WORD

Pointer to device strategy WORD

Pointer to device interrupt WORD

N arne/unit field 8 BYTES

Next evice Header Field

3-6

The pointer to the next device header field s a doubleword field (offset followed by segment) that is set byDOS at the time the device driver s loaded. However,it is important that this field be set to 1 prior to loadtime (when t is on the disk as a .COM file) unless theres more than one device driver in the .COM file. f theres more than one driver in the file, the first word of the

double word pointer should be the offset of the nextdriver s Device Header.

Note: If there is more than one device driver inthe .COM file, the l st driver in the file must havethe pointer to next Device Header field set to 1.



ttribute Field

The next field in the header describes to the system theattributes of the device. They are as follows:

bit 15 = 1 if character deviceo f block devicebit 14 = 1 if IOCTL is supported

if it is notbit 13 = 1 if non IBM format block only)

o f IBM formatbit 3 = 1 if current clock device

o f it is notbit 2 = 1 if current NUL device

o f it is notbit 1 = 1 if current standard output device

o f it is notbit 0 = 1 if current standard input device

o f it is not

All other bits must be off.

The most important bit is bit 15, which tells the systemthat it is a block or a character device. With theexception of bits 13 and 14, the rest are for givingcharacter devices special treatment and mean nothingon a block device. These special treatment bits allowyou to tell DOS that your new device driver is the new

standard input device and standard output device theCON device). This can be done by setting bits 0 and 1to 1 Similarly, a new CLOCK device could beinstalled by setting that attribute bit.

Although there is a NUL device attribute bit, the NUL

device cannot e reassigned This is an attribute thatexists for DO S so it can tell if the NUL device is beingused. The non IBM format bit applies only to blockdevices and affects the operation of the Get BPB BIOSParameter Block) device call covered later in thischapter). The other bit of interest is the IOCTL bit.This is used for both block and character devices, andtells DOS whether the device is able to handle controlstrings through the IOCTL system call).

3 7



f a driver cannot process control strings, it shouldinitially set this bit to O This way DOS can return anerror if an attempt is made through the IOCTL systemcall to send or receive control strings to the device. Adevice that is able to process such control strings should

initialize this bit to1 For

devicesof

this type,DOS

will make the calls to the IOCTL input and the IOCTL

output device functions to send and receive IOCTL

strings.

The IOCTL functions allow data to be sent to and fromthe device without actually doing a normal read orwrite. In this way, the device can use the data for its

own use (like setting a baud rate, stop bits, changingform lengths, etc.). t is up to the device to interpret theinformation passed to it, but it must not be treated as anormal I O request.

Strategy and Interrupt Routines

These two fields are the pointers to the entry points of

the strategy and interrupt routines. They are wordvalues, so they must be in the same segment as theDevice Header.

Name ield

3 8

This is an 8-byte field that contains the name of acharacter device, or the number of units of a blockdevice. I f it is a block device, the number of units canbe put in the first byte. This is optional, because DOS

will fill in this location with the value returned by thedriver's INIT code. (Refer to Installation of DeviceDrivers in this chapter.)



reating a Device Driver

In order to create a device driver that DOS can install,a . CO M file must be created with the Device Header atthe start of the file. Remember that for device drivers,the code should not be originated at 100H, but rather atO The link field pointer to next Device Header) shouldbe 1 unless there is more than one device driver in the

COM file. The attribute field and entry points must be

set correctly.

f it is a character device, the name field should be filledin with the name of that character device. The name canbe any legal 8-character filename.

DOS always processes install able device drivers beforehandling the default devices, so to install a new CON

device, simply name the device CON Uust be sure to setthe standard input device and standard output devicebits in the attribute word on a new CON device). Thescan of the device list stops on the first match, so theinstall able device driver takes precedence.

Note: Because DOS can install the driver

anywhere in memory, care must be taken in anyfar memory references. You should not expect thatyour driver will always be loaded at the sameplace every time.

3-9



Installation o evice rivers

3-10

DOS Version 2.10 allows new device drivers to beinstalled dynamically at boot time by reading andprocessing the device options in the CONFIG.SYS file.

DOS calls a device driver at it's strategy entry pointfirst, passing in a Request Header the informationdescribing what DOS wants the device driver to do.

The strategy routine does not perform the request, butrather it enqueues the request (saves a pointer to theRequest Header). The second entry point is theinterrupt routine, and s called by DOS immediatelyafter the strategy routine returns. The ' interruptroutine is called with no parameters. Its function is toperform the operation based on the queued request andset up any return information.

DOS passes the pointer to the Request Header inES:BX. This structure consists of a fixed length header(Request Header) followed by data pertinent to theoperation to be performed.

Note: It is the responsibility of the device driverto preserve the machine state (for example, saveall registers on entry, and restore them on exit).

The stack used by DOS will have enough room onit to save all of the registers. If more stack space s

needed, it s the device drivers responsibility toallocate and maintain another stack.

All calls to device drivers are FAR calls, andFAR returns should be executed to return to DOS.(See Sample Device Driver listing at the end ofthis chapter.)



Request Header

BYTE length in bytes of theRequest Header plus any data atthe end of the Request Header

BYTE unit codeThe subunit the operations for minor device).

Has no meaning for characterdevices.

BYTE command code

WORD Status

8 BYTE areareserved for DOS

Data appropriate to theoperation

Unit ode

The unit code field identifies which unit in your devicedriver the request s for. For example, if your devicedriver has 3 units defined, then the possible values of

the unit code field would be 0, I and 2.

3-11



ommand ode

3-12

The command code field in the Request Header canhave the following values:

Code Function

0 INIT

1 MEDIA CHECK Block only, NOP forcharacter)

2 BUILD BPB Block only, NOP for character)

3 IOCTL input only called if IOCTL bit is 1

4 INPUT read)

5 NON-DESTRUCTIVE INPUT NO WAIT

Character devices only)

INPUT STATUS Character devices only)

7 INPUT FLUSH Character devices only)

8 OUTPUT write)

9 OUTPUT write) with verify

10 OUTPUT STATUS Character devices only)

11 OUTPUT FLUSH Character devices only)

12 IOCTL output only called if IOCTL bit is 1

BUILD BPB and MEDIA CHECK

BUILD BPB and MEDIA CHECK for block devicesonly, are explained here.



DOS calls MEDIA CHECK first for a drive unit. DOS

passes it's current Media Descriptor byte (see Media

Descriptor Byte later in this chapter). MEDIA

CHECK returns one of the following four results:

• Media Not Changed

• Media Changed

• Not Sure

DOS will call BUILD BPB under the following twoconditions:

• f Media Changed s returned

• I f Not Sure s returned and there are no dirtybuffers (buffers with changed data, not yet writtento disk).

tatus Word

ER

R

The status word in the Request Header.

RESERVEDB DUS N

ERROR CODE bit 15 on

The status word s zero on entry and s set by the driverinterrupt routine on return. Remember that this word s

stored low byte first n memory.

Bit 8 s the done bit. When set it means the operation s

complete. For DOS 2.10 the Driver just sets it to onewhen it exits.

3-13



3-14

Bit 15 is the error bit. If it is set, then the low 8 bits ofthe status word indicate the error. The errors are:

Write Protect Violation1 Unknown Unit

02 Device Not Ready03 Unknown command4 e R e Error

05 Bad Drive Request Structure Length06 Seek Error07 Unknown Media08 Sector Not Found09 Printer Out of Paper

OA Write FaultOB Read Faulto e General Failure

Bit 9 is the busy bit that is set by status calls.

For output on character devices: f it is 1 on return,a write request if made) would wait for completion of acurrent request. If it is 0, there is no current request,and a write request if made) would start immediately.

For input on character devices with a buffer: f it is1 on return, a read request if made) would go to thephysical device. f it is 0 on return, then there arecharacters in the device buffer and a read would return

quickly, it also indicates that the user has typedsomething. DOS assumes all character devices have aninput typ he d buffer. Devices that do not have themshould always return busy 0 so that DOS will notcontinuously wait for something to get into a buffer thatdoes not exist.



One of the functions defined for each device is INIT.

This routine is called only once when the device is

installed and never again. There are several thingsreturned by the IN IT routine. First, there is a locationof the first free byte of memory after the device driver

like a terminate and stay resident) that is stored in theending address field. In this manner, initialization codecan be used once and thrown away in order to savespace.

After setting the ending address field, a characterdevice driver can set the status word and return. Whileblock devices are installed in the same way as characterdevices, they must return additional information. Thenumber of units for the device driver is returned, andthis determines the logical names that the devices willhave. For example, if the current maximum logicaldevice letter is F at the time of the install call, and theblock device driver INIT routine returns 3 units, thentheir logical names will be G H, and 1 This mapping is

determined by the position of the driver in the devicelist, and the number of units on the device. The numberof units returned by INIT will override the value in thename/unit field of the Device Header.

In addition, a pointer to a BPB BIOS ParameterBlock) pointer array is also returned. This is a pointerto an array of word pointers, where is the number of

units defined. These word pointers point to BPBs. Inthis way, if all of the units are the same, the entire arraycan point to the same BPB in order to save space.

Note: This array must be protected below thefree pointer set by the return).

The BPB BIOS Parameter Block) contains informationpertinent to the devices like sector size, sectors perallocation unit, etc. The sector size in the BPB cannotbe greater than the maximum allowed set at DOS

initialization time).

3-15



t h e last thing that INIT of a block device must passback is the media descriptor byte . This byte meansnothing to DOS, but s passed to devices so that theyknow what parameters DOS s currently using for aparticular Drive-Unit.

Block devices may take several approaches; they maybe dumb or smart A dumb device would define a unit(and therefore a BPB) for each possible media drivecombination. Unit 0 = drive 0 single side, unit 1 =drive 0 double side, etc. For this approach, mediadescriptor bytes would mean nothing. A smart devicewould allow multiple media per unit. In this case, the

BPB table returned at INIT must define space largeenough to accommodate the largest possible mediasupported (sector size in BPB must be as large asmaximum sector size that DOS s currently using).Smart drivers will use the media byte to passinformation about what media s currently n a unit.

Function all Parameters

3-16

All strategy routines are called with ES:BX pointing tothe Request Header. The interrupt routines get thepointers to the Request Header from the queue thestrategy routines store them in. The command code inthe Request Header tells the driver which function to

perform.Note: All DWORD pointers are stored offsetfirst, then segment.



N T

Command code=O

ES:BX

13 BYTE Request Header

BYTE number of unitsnot set by character devices)

DWORD Ending Address

DWORD Pointer to BPB arraynot set by character devices)

The driver must do the following:

• Set the number of units block devices only).

• Set up the pointer to the BPB array block devicesonly).

• Perform any initialization code to modems,printers, etc.).

• Set up the ending address for resident code.

• Set the status word n the Request Header.

Note: f there are multiple device drivers in asingle .COM file, the ending address returned bythe last INIT called will be the one DOS uses. For

the sake of simplicity, it s recommended that all of

the device drivers in a single .COM file return the

same ending address.

3-17



MEDIA CHECK

Command code= 1

ES:BX

13-BYTE Request Header

BYTE Media Descriptor from DOS

BYTE return information

The driver must perform the following:

• Set the return byte:-1 Media has been changedo Don t know if media has been changed1 Media has not been changed

• Set the status word in the Request Header.

BUILD BPB BIOS Parameter Block

Command code=2

ES:BX


BYTE Media Descriptor from DO S

DWORD Transfer Address buffer address)

DWORD Pointer to BPB table


• Set the pointer to the BPB.

3-18• Set the status word in the Request Header.



The driver must determine the correct media that is

currently in the unit to return the pointer to the BPBtable. The way the buffer is used pointer passed byDOS is determined by the non-IBM format bit in theattribute field of the device header. f the bit is zero

device is IBM format compatible) then the buffercontains the first sector of the FAT most importantlythe FAT id byte). The driver must not alter this bufferin this case. f the bit is a one, then the buffer is a onesector scratch area that can be used for anything.

If the device is IBM format compatible, then it must betrue that the first sector of the first F AT is located at

the same sector for all possible media. This is becausethe FAT sector is read efore the media is actuallydetermined.

The information relating to the BPB for a particularmedia is kept in the boot sector for the media. Inparticular, the format of the boot sector is

3 BYTE near JUMP to boot code

8 BYTE a EM name and version

WORD bytes per sector

BYTE sectors per allocation unitmust be a power of 2)

WORD reserved sectorsstarting at logical sector 0)

BYTE number of FATs

WORD number of root dir entriesmaximum allowed)

3 19



3-20

WORD number of sectors in logical imagetotal sectors in media, including boot sector,

directories, etc.)

BYTE media descriptor

WORD number of sectors occupied by a single F T

WORD sectors per track

WORD number of heads

WORD number of hidden sectors

The three words at the end are optional. DOS does notcare about them because they are not part of the BPB.They are intended to help the device driver understandthe media. Sectors per track may be redundant becauseit can be calculated from the total size of the disk. The

number of headss

useful for supporting differentmulti-head drives that have the same storage capacitybut a different number of surfaces. The number ofhidden sectors s useful for supporting drive partitioningschemes.



MEDI Descriptor yte

Currently the media descriptor byte has been definedfor a f w media types:

edia descriptorbyte > x x x

7 6 5 4 3 2 0

Bit Meaning

o 1=2 sided O=not 2 sided=8 sector O=not 8 sector

2 1=removable O=not removable3-7 must be set to 1

Examples of current DOS media descriptor bytes:

• 5 1 / 4 ~Diskettes:

hex FC 1 sided 9 sectorhex FD 2 sided 9 sectorhex FE 1 sided 8 sectorhex FF 2 sided 8 sector

• Fixed Disks:

hex F8 Fixed disk)

• 8 Diskettes:

Hex FE IBM 3740 Format). Single sided,single density, 128 bytes per sector, soft sectored,4 sectors per allocation unit, reserved sector,2 FATs, 68 directory entries, 77*26 sectors.

3-21



Hex FD IBM 3740 Format). Dual sided, singledensity, 128 bytes per sector, soft sectored,4 sectors per allocation unit, 4 reserved sectors,2 FATs, 68 directory entries, 77*26 sectors.

Hex FE. Single sided, double density,1024 bytes per sector, soft sectored, 1 sector perallocation unit, 1 reserved sector, 2 FATs,192 directory entries, 77*8*2 sectors.

Note: The two MEDIA descriptor bytes that arethe same for 8 diskettes hex FE) s not amisprint. To establish whether a diskette s single

density or double density, a read of a singledensity address mark should be made. If an erroroccurs, the media s double density.

NPUT r OUTPUT

Command codes=3,4,8,9, and 12

ES:BX


BYTE Media descriptor byte

DWORD transfer address buffer address)

WORD byte/sector Count

WORD starting sector numberno meaning on character devices)

3-22




• Do the requested function.

• Set the actual number of sectors bytes)

transferred.


Note: No error checking s performed on anIOCTL call. However, the driver must set thereturn sector byte) count to the correct numbertransferred.

The following applies to block device drivers:

Under certain circumstances the device driver may beasked to do a write operation of 64K bytes that seemsto be a wr p round of the transfer address in thedevice driver request packet. This arises due to anoptimization added to the write code in DOS. t willonly happen on WRITEs that are within a sector size of

64 K bytes on files that are being extended past thecurrent end of file. It s allowable for the device driverto ignore the balance of the WRITE that wraps around,if it so chooses. For example, a WRITE of 1 H

bytes worth of sectors with a transfer address of xxxx: 1could ignore the last two bytes.

Remember: A program that uses DOS function callscan never request an input or output operation of morethan F F F F H bytes; therefore, a wrap around n thetransfer buffer) segment cannot occur. t s for thisreason that you can ignore bytes that would havewrapped around in the transfer segment.

3-23



on Destructive Input o Wait

Command code=5

ES:BX


BYTE read from device


• Return a byte from the device.


This call is analagous to the console input status call onprevious versions of DOS f the character devicereturns busy bit = 0 characters in buffer), then the nextcharacter that would be read s returned. This characteris not removed from the input buffer hence the termNon Destructive Input). This call allows DOS to lookahead one input character.

ST TUS

3-24

Command codes= 6

and 10ES:BX


All the driver must do s perform the operation and set

the status word in the Request Header accordingly.



LUSH

Command codes = and 11

ES:BX


This call tells the driver to flush terminate) allpending requests that it has knowledge of Its primaryuse is to flush the input queue on character devices.The driver must set status word in the RequestHeader upon return.

3 25



The LO KS Device

3-26

A popular add on feature is a Real Time Clock

board. To allow these boards to be integrated into thesystem for TIME and DATE, there is a special devicedetermined by the attribute word) which is the

CLOCK$ device. In all respects, this device definesand performs functions like any other character devicemost functions will be set done bit, reset error bit,

return). When a read or write to this device occurs,exactly 6 bytes are transferred. The first two bytes are aword which is the count of days since 1-1-80. The thirdbyte is minutes, the fourth hours, the fifth 1/100seconds, and the sixth seconds. Reading the CLOCK$device gets the date and time, writing to it sets the dateand time.



Sample Device Driver

345678910

12131415

61718

9202122

23242526

272829303132333435

3637

3839404142434445

464748495051525354555657

0000

00000000

0001000200030005

= 0000= 0001= OOOE= 0004= 0012= 0002= 0014= 0002

= OOOE

= 0012= 0004

, PROLOG, THIS IS AN INSTALLABLEDEVICE DRIVER FOR AN; IN STORAGE DISKEm I VIRTUALI WITH 180K CAPACITY.

,SEG SEGMENTPARA PUBLIC CODE

hATUS

M A C R O I S

MACROIFIDN

ORENOIFIFIDN

ORENDI

IFIDNOR

ENOIFIFNB

ORENDIFENDH

STATE,ERR,RC(STATE>, (DONE}ES. WORD PTR SRH_STAJLD[BXJ,0100H

(STATE>, (BUSY>ES. WORD PTR SRH_STAJLD[BXJ,0200H

(ERR} , (ERROR)ES: WORD PTR SRH_STAJLD[BXJ ,1000H

mC}ES. WORD PTR SRH_STAJLD[BXJ,RC

E Q U AT E S

: READ/WRITE

~ R H EQU a ,STATIC REQUEST HEADERSTARTSRH LEN EQU 13SRH:LENJLD EQU SRH

.. .. .. LENGTH.. FIELD

SRH UCD LO EQUSRH:CCD:FLD EQUSRH_STAJLD EQUSRH_RESJLD EQU

SRHt1SRH+2SRH+3SRH+5

UNIT CODE FIELDCOMMANDCODE FIELDSTATUS FIELDRESERVED AREA FIELD

~ D EQUHD LEN EQUDTA EQUDTA LEN EQUCOUNT EQUCOUNT_LEN EQUSSN EQUSSN_LEN EQU

; HEDIA CHECK

~ U Y T EEQU

; BUILD BPB

~ P BPTR EQUBPBA:PTR_LEN EQU

; INIT

SRHtSRH_LEN1MDfHD_LEN4DTAtDTA_ EN2COUNTtCOUNT_LEN2

HDfHD_LEN

DTMDTA_LEN4

; E ~ I D E S C ~ I P T O RBYT,E LENGTH

; DISK TRANSFER ADDRESS; DTA LENGTH; BYTE SECTOR COUNT; .. LENGTH; STARTING SECTOR NUMBER

.. .. .. LENGTH

,BYTE RETURNED FRDHDRIVER

; POINTER TO BPB.. . . . . LENGTH

3 27



5859 000060 000161 OOOE62 001063 000464 001265 0014666768 00006970 000071

= 00007273 0000 FF FF FF FF74 0004 200075 0006 00E1 R76 0008 OOEC R77 OOOA 0178 OOOB 0779 7?80818283 0012 777184 00148586 = 001687 0016 020088 0018 0189 0019 0001

90 0018 0291 OOlC 004092 DOlE 016893 0020 Fe94 0021 00029596 0023 0016 R9798 0025 717?99 0027 00100 0028 0000101 002A 0000102 002C 77?????7103 = 0030104 0030 03105 00106107108 0033 49 42 40 20 20 32

1092E

30110 003B 0200111 0030 01112 003E 0001

3 28

~ I T EQUUNITS LEN EQUBR ADiiR 0 EQUBR-ADDR-l EQU

SRHtSRH LEN1 -UNITStUNITS LENBR ADDR0+2-4 - -BR- ADDR-LEN EQU

BPB PTR-OFF EQUBPB)T SEG EQU

BR AOOR O+8R AOOR LEN

~ O S K

BEGIN'

START

BPS_PTR)FF+2 -

PROC FARASSUME CS: CSEG, ES: CSEG,DS: CSEG

EQU~ E X TDEVATTRIBUTESTRATEGYINTERRUPTOEV_NAME

S P E C I L D E V I C EOD -1

OW 2000HOW DEV STRATEGYOW DEV-INTDBDB 7 DUP ?)

OFF OWRH-SEG OW ?; BIOS PARAMETERBLOCKBPB EQU

W 512DB 1OW 1

DB 2OW 64w 360

DB OFCHOW 2

~ P PTR OW BPB; cURRENT VIRTUAL DISK INFORMATIONTOTAL OW ?VERIFY DB 0START SEC OW 0VDISK-PTR w 0USER iiTA 00 7BOOT- REC EQU

- DB 3 DUPIO)

DB

· w

DB

OW

IBM 2.0

51211

H E D E R; POINTER TO NEXT DEVICE;BLOCK DEVICE INON-IBM FORMAT;POINTER TO DEVICE STRATEGY; POINTER TO DEVICE INTERRUPT HANDLER;NUMBEROF BLOCK DEVICES; 7 BYTES OF FILLER

,REQUEST HEAOEROFFSET;REQUESTHEADER SEGI ENT

; SECTOR SIZE;SECTORS/ALLOCATIONUNIT;NUMBEROF RESERVED SECTORS

;NUMBER OF FATS;NUMBER OF DIRECTORY ENTRIES; TOTAL NUMBEROF SECTORS,MEDIA DESCRIPTOR;NUMBER OF SECTORS OCCUPIED BY FAT

;BIOS PARAMETER BLOCK POINTER ARRAY (1 ENTH

; TOTAL SECTORS TO TRANSFER; VERIFY 1=YES, O=NO; STARTING SECTOR NUMBER; STARTING SEGMENTOF VIRTRUAL DISK; POINTER TO CALLERS OISK TRANSFER ADDRESS; DUMMYODS BOOTRECORD; 3 BYTE JUMP TO BOOT CODE INOT BOOTABLE)

; VENDOR IDENTIFICATION

;NUMBEROF BYTES IN A SECTOR,1 SECTOR PER ALLOCATION UNIT; 1 RESERVED SECTOR



113114115116117118119120121122123124125

126127128129130131132133134135186137138139140141142143144

145146147148149150151152153154155156157158159160161162163

164165166167

0040 020041 00400043 01680045 Fe0046 0002

00480048 0105 ROOLl 0188 R004C 01CC R004E 0212 R

0050 0212 R0052 0212 R0054 0212 R0056 0212 R0058 0241 R005A 0280 R005C 0212 R005E 0212 R0060 0212 R

00620062 26: 8B 47 OE

0066 2E: A3 002C R006A 26 8B 47 10006E 2E. A3 002E R0072 26: 8B 47 120076 32 E4

0078 2E: A3 0025 R007C C3

0070

00700070 2E Ai 0028 R0081 B9 00200084 F7 E10086 2E: 8B 16 002A R008B 03 000080 BE O

OOBF 33 F60091 2E. Al 0025 R0095 B9 02000098 F7 E1009A OB CO

009C 75 03009E sa FFFFOOAl

OOAl 91A2 C3

00A3

2 ;2 FATS,NUMBER OF DIRECTORY ENTRIES;360 TOTAL SECTORS IN IMAGE

DBowow08ow

64360OFCH

2; TELLS DOS THIS IS A SINGLE SIDED 9 SECTOR DISK;NUMBER OF SECTORS IN FAT

~ U N T B

FUNCTION TABLE

LA8ELowW

owW

ow

BYTEINITMEDIA CHECK

BUILO-BP8DCTL-ININPUT-

; INITIALIZATION;MEDIA CHECK IBLOCK ONLYl;BUILO BPB,IOCTL INPUT,INPUT I READ)

ow NO INPUTIN-STATIN-FLUSHOUTPUT

;NON DESTRUCTIVE INPUT NO W lT ICHAR ONLY); INP[jr STATUS U U

L O C A L

iN SAVE PROC

owW

owW

owW

ow

OUT VERIFYOUT-STATOUT)LUSHIOCTL_OUT

P R O C E D U R E S

NE R

; NPUT FLUSH,OUTPUT IWRITE),OUTPUT (WRITE) WITH VERIFY;OUTPUT STATUS,OUTPUT FLUSH,IOCTL OUTPUT

- MOV AX,ES:WORO PTR OTA(BXJ ;SAVE CALLERS OT

CS:USER_OTA,AXOV

MOV

MOV

MOV

XORMOV

RET

AX,ES:WORD PTR DTA+2(BXJCS .USER_DTA+2 ,AX

X ,ES: WORD PTR COUNT(BXJ ; GET NUMBER OF SECTORS TO READAH,AH

CS:TOTAL,AX ,MOVENUMBER OF SECTORS TO

TOTAL

IN_SAVE ENOP

~ OOR PROC NE R

- MOV AX,CS START_SECMOV CX,20HI'RJl CXMOV OX,CS.VOISK_PTR

DD OX ,AXMOV OS ,oxXOR 51 51MOV AX,CS:TOTALMOV CX,512MUL CXOR X ,AXJNZ MOVE ITMOV AX, OFFFFH

MOVE IT:

-XCHG

CX,AXRETCALC_ADOR ENOP

;GET STARTING SECTOR NUMBER

;MOV 512 TO CX SEGMENT STYLE;MULTIPLY TO GET ACTUAL SECTOR

,GET SEGMENT OF VIRTUAL DISK,ADO THAT SEGMENT TO INITIAL SEGMENT

, SAVE THAT S THE ACTUAL SEGMENT

, IT S ON A PARAGRAPH BOUND RY

, TOTAL NUMBER OF SECTORS TO RE D

,BYTES PER SECTOR

; MULTIPL Y TO GET COPY LENGTH,CHECK FOR GREATER THAN 64K

;MOVE IN FOR 64K

,MOVE LENGTHTO CX

3 29



168 00A3 SECTOR_READ PROC NEAR169 00A3 EB 0070 R CAll CALC ODR ;CALCULATETHE STARTING SECTOR170 00A6 2E: BE 06 002E R HOV ES ,CS:USER_OTA+2 ;SET DESTINATION (ES: 01) TO POINT171 OO B 2E: BB 3E 002C R HOV OI,CS:USER_OTA ; TO CALLERS OT

172; CHECK FOR OT WR P IN C SE WE C HE THROUGH VIA VERIFY73

174175 OOBO 8B C7 MOV AX,OI ; GET OFFSET OF OT

176 00B2 03 Cl DD AX,CX ; DD COPY LENGTH TO IT177 00B4 73 07 JNC RE D COPY ; C RRY FLAG 0, NO WR P

178 00B6 B8 FFFF HOV AX,OFFFFH ;MAX LENGTH179 0089 2B C7 SUB AX,OI ; SUBTRACT OT OFFSET FROM M X

180 OOBB 8B CB HOV CX,AX ;USE THAT S COPY LENGTH TO AVOID WR P

181OOBO

READ_COPY:lB2 OOBO F3 A4 REP MOVSB ;00 THE READ183 OOBF C3 RET

184 OOCO SECTOR_READ ENOP

185~ E T O R _ W R l T EPRDC NEAR86 OOCO

lB7 OOCO EB 0070 R CALL CALC_AOOR ;CALCULATESTARTING SECTOR188 ooca lE PUSH 05189 00C4 07 POP ES ,ESATABLISH AOORESSABILITY190 00C5 88 FE MOV DI SI ; ES: 01 POINT TO DISK191 00C7 2E: BE lE 002E R MeV 05 ,CS :USER_OTA+2 ; 05: SI POINT TO CALLERS OT

192 ooce 2E: 8B 36 002C R MOV SI,CS :USER_OTA193

: CHECK FOR OT WR P94195196 0001 88 C6 MeV AX,SI ; HOVE OT OFFSET TO AX197 0003 03 Cl DD AX,CX ;AOD COPY LENGTH TO OFFSET198 0005 73 07 JNC WRITE COPY ;C RRY FLAG 0, NO SEGMENT WR P

199 0007 B8 FFFF HOV AX,OFFFFH ;MOVE IN M X COPY LENGTH2 OOD

28 C6SUB

AX,SI ;SUBTRACT OT OFFSET FRDM M X

201 OOOC 8B CB MeU ex ,AX ,USE AS NEW COPY LENGTH TO AVOID WR P

202 OOOE WRITE_COPY:203 OOOE F3 A4 REP MOUSB ;00 THE WRITE204 OOEO C3 R T

205 OOEl SECTOR_WRITE ENOP

3 30



206207208209210211212213214215216217218

21922022122222322422522622722822923231232233234235236237

238239240241242243244245246247248249250251252253254255256

257258259260

OOElOOEl 2E. Be 06 0014 R00E6 2E: 89 lE 0012 ROOEB CB

OOEC

OOEC FCOOED lEOOEE 06OOEF 50OOFO 53OOFl 5100F2 5200F3 5700F4 56

00F5 26. 8A 47 0200F9 DO COOOFB 80 3E 0048 ROOFF 32 E40101 03 F80103 FF 25

01050105 OE0106 5A0107 2E: 80 06 OCAO ROlOC Bl 04010E 03 C80110 03 000112 2E 89 16 OOCA R0117 B8 2000011A 03 00011C 26: C7 47 OE 00000122 26: 89 57 100126 26: C6 47 00 01012B 80 16 0023 R012F 26. 89 57 120133 26: 8C 4F 140137 2E: 8E 06 OOCA R

013C 33 FF013E 80 36 0030 R0142 B9 0018

145 F3 A4

PAGE

D E V I C E S T R AT E G Y

bEV STRATEGY:- MOV CS:RftSEG,ES ;SAVE SEGMENT OF REQUESTHEADERPOINTER

MOV CS RH_OFF, BX ; SAVE OFFSET OFRET

D E V I C E I N T E R R U P T H A N D L E R

DEV INT:, PRESERVE MACHINE STATE ON ENTRY

CLDPUSH OSPUSH ESPUSH AXPUSH BXPUSH CXPUSH OXPUSH 1PUSH SI

; DO THE BRANCHACCORDING TO THE FUNCTION PASSED

INITiNn:

MOVR LLEAXORADDJMP

AL,ES: [BXJ+2AL lDI,FUNTABAH,AHOI,AXIoIORD PTR[DIJ

CSOXAX,CS VOISKCL,4

;GET FUNCTION BYTE,GET OFFSET INTO TABLE;GET ADDRESSOF FUNCTION TABLE

;CURRENTCS T OX;GET ADDRESS OFVIRTUAL DISK

AX,CL ;OIVIDE BY 16 (PARAGRAPH FORM)OX,AX ,ADO TO CURRENTCS VALUE

PUSHPOPLEAMOVRORADDMOVMOVADOMOVMOVMOVLEAMOVMOVMOV

XORLEAMOVMOVSB

CS.VDISK_PTR,OX ;SAVE AS STARTING SEGMENTOF VIRTUAL DISKAX,2000H ; ADO 2DOOH PARAGRAPHSTO STARTINGOX,AX ; SEGMENT OFVIRTUAL DISKES WORDPTR BR_AOOR_OEBXJ,OES:BR_AODR_HBXJ,DX ,MAKE THAT THE BREAKADDRESSES:BYTE PTR UNITS[BXJ,l ;NUMBER OF DISKETTE UNITSOX,BPB_PTR ;GET ADDRESSOF BPB POINTER ARRAYES:BPB_PTR_OFFCBXJ ,OX ,SAVE OFFSET IN DATA PACKETES:BPB_PTR_SEGrBXJ,CS ;SAVE SEGMENTIN DATA PACKETES,CS:VOISK_PTR ;GET STARTING SECTOROF VIRTUAL DISK

01,01 ;ZERO OUT 1 (BOOT RECORDSI BOOT_REC ;ADDRESS OF BOOT RECORD

REPCX,24

:COPY 24 BYTES OF BOOTRECORD

3 31



261 147 2E: r T 06 0028 R 0001 MOV CS:WORDPTR START_SEC,l262 014E 2E: C7 06 0025 R 0002 MOV CS:WORD PTR TOTAL,2263 155 E8 007D R CALL CALC_ADDR ;CALCULATE ADDRESS OF LOGICAL SECTOR 1264 158 lE PUSH OS265 159 07 POP ES266 015A 8S FE MOV 01 51 ;MOVETHAT ADDRESS TOES:DI267 015C 32 CO XOR AL,AL268 015E F3t AA REP STOSB ;ZERO OUT FAT AREA269 0160 C6 04 FC MOV OS: BYTE PTR CSIJ, OFCH ;SET THE FIRST FAT ENTRY27 163 C6 44 01 FF MOV OS: BYTE PTR lCSIJ OFFH271 167 C6 44 02 FF MOV DS:BYTE PTR 2CSlJ,OFFH272 168 lE PUSH DS ;SAVE POINTER TO FAT273 016C 56 PUSH 51 ; ON THE STACK274 0160 2E: C7 06 0028 R 0003 MOV CS:WORD PTR START_SEC,3275 174 2E: C7 06 0025 R 0002 MOV CS:WORDPTR TOTAL,2276 0178 EB 007D R CALL CALC_ADDR ;CALCULATE ADDRESS OFLOGICAL SECTOR 3277 O 7E lE PUSH OS278 017F 07 POP ES279 01BO 8B FE HOV 01 51 ;MOVE THAT ADDRESS TO ES:DI280 0182 5E POP SI281 01B3 lF POP OS ;RESTORE ADDRESS TO FIRST FAT282 184 F3t A4 REP MOVS8 ,COPY FIRST FAT TO SECOND FAT283 186 2E: C7 06 0028 R 0005 MOV CS:WORDPTR START_SEC,5

84 0180 2E: C7 06 0025 R 0004 MeV CS: WORD PTR TOTAL,4285 0194 EB 007D R CALL CALC ADDR ;CALCULATE ADOR OFL.S. 5 START OF DIR)286 0197 32 CO XOR A L ~287 0199 lE PUSH OS288 019A 07 POP ES ; SET UP ES: DI TO POINT TO IT

89 0198 33FF XOR 01 01290 0190 F3t M REP STDSB ;ZERO OUT DIRECTORY291 019F 2E: BE 06 0014 R MOV ES ,CS: RH_SEG ; RESTORE ES: ax TO REQUEST HEADER292 01A4 2E: BB lE 0012 R MOV BX,CS:RH_OFF293 STATUS DONE NOERROR0 ;SET STATUS WORD IOONE, NDERRORI

294 01A9 26: l 4F 03 0100 OR ES:WORO PTR SRH_STAJLDCBXJ,0100H295 OlAF 26: Bl 4F 03 0000 OR ES: WORD PTR SRH_STAJLDCBXJ,0296 185 E9 0288 R JHP EXIT297

; MEDIA CHECK9899

kOlA_CHECK:00 188 ;MEDIA CHECK BLOCK ONLY)301302 SET MEDIA NOT CHANGED303304 188 26: C6 47 OE 01 MeV ES: BYTE PTR RET_BYTECBXJ 1 ; STORE IN RETURN BYTE305 STATUS DONE,NDERROR,0 ;TURN ON THE DONE BIT3 6 01BO 26: l 4F 03 0100 OR ES. WORD PTR SRH_STA_FLDCBXJ,0100H307 01C3 26: 81 4F 03 0000 OR ES.WORDPTR SRH_STAJLDCBXJ,O308 01C9 E9 0288 R JMP EXIT309

; BUILD BIOS PARAI1ETERBLOCK10311

~ I L D _ B P B12 Olec313 Olec 06 PUSH ES ; SAVE SRH SEGMENT314 01CO 53 PUSH 8X ; SAVE SRH OFFSET315 OlCE 2E: C7 06 0028 R 0000 MOV CS:WORD PTR START_SEC,O

3 32



371 0257 2E: 8B l 0012 R MOV 8X,CS:llH_OFF ;RESTORE ES:8X S REQUEST HE DER POINTER372 025C 2E. BE 06 0014 R MOV ES,CS:llH_SEG373 0261 2E 80 3E 0027 R 00 CMP CS: BYTE PTIl VERIFY,0 ; WRITE VERIFY SET?374 0267 74 08 JZ NO VERIFY ,NO, NO WRITE VERIFY375 0269 2E: C6 06 0027 R 00 MOV CS:BYTE PTR VERIFY,0 ;RESET VERIFY INDICATOR376 026F EB Al JMP INPUT ; RE D THOSE SECTORS B CK IN377 0271 NO_VERIFY:378 STATUS DONE,NOERROR , 0 ; SET DONE, NO ERROR IN STATUS WORD

379 0271 26: 81 4F 03 0100 OR ES.WORD PTR SllH_STAJLD[BXJ ,0100H380 0277 26: 81 4F 03 0000 OR ES:WORD PTII SllH_STAJLD[BXJ,O381 0270 EB 09 90 JMP EXIT382 02BO OUT_VERIFY. ;OUTPUT (WRITE) WITH VERIFY383 0280 2E' C6 06 0027 R 01 MOV CS . BYTE PTR VERIFY,1 ; SET THE VERIFY FLAG384 0286 EB 89 JMP OUTPUT ; BR NCH TO OUTPUT ROUTINE385 ; COMMON EXIT86387

~ I T88 0288389 0288 E POP SI ;RESTORE ALL OF THE REGISTERS390 0289 5F POP 01391 028A 5A POP OX

392 028B 59 POP CX

393 028C 5B POP 8X394 0280 58 POP X

395 02BE 07 POP ES

396 028F IF POP OS

397 0290 cll R T

398 0291 O P:399 ; MACRO TO ALIGN THE VIRTUAL DISK ON A P R GR PH BOUND RY

400 f (S-START MOD 16401 02A0 ORG (S-STAIlT +16-( (S-START) MOD 16)402 endl f

403 = 02A0 VOISK EQU

404 02A0 VOSK ENOP405 02A0 CSEG ENDS

406 END BEGIN

3 34



Chapter 4 O S Disk Allocation

Contents

OS Disk Directory 4 4OS File Allocation Table 4 8

How to Use the File Allocation Table 4 10

4·



4 2



All disks and diskettes formatted by DOS are createdwith a sector size of 512 bytes. The DOS area ( entirediskette for diskettes, DOS partition for fixed disks) is

formatted s follows:

Boot record - variable size

First copy of file allocationtable - variable size

Second copy of file allocationtable - variable size

Root directory - variable size

Data area

Allocation of space for a file (in the data area) is doneonly when needed (it is not pre-allocated). The space isallocated one cluster (unit of allocation) at a time. Acluster is always one or more consecutive sectornumbers, and all of the clusters for a file are chainedtogether in the File Allocation Table.

The clusters are arranged on disk to minimize headmovement for multi-sided media. All of the space on a

track (or cylinder) is allocated before moving on to thenext track. This is accomplished by using the sequentialsector numbers on the lowest-numbered head, then allthe sector numbers on the next head, and so on until allsectors on all heads of the track are used. Then, thenext sector to be used will be sector 1 on head 0 of thenext track.

F or fixed disk, the size of the file allocation table anddirectory are determined when FORM T initializes it,and are based on the size of the DOS partition.

4-3



Sides

1212

F or diskettes, the following table can be used:

Sectors/ FAT size Dir Dir Sectors/Track Sectors Sectors Entries Cluster

8 1 4 64 18 1 112 29 2 4 64 19 2 112 2

Files in the data area are not necessarily written

sequentially on the disk. The data area space sallocated one cluster at a time, skipping over clustersalready allocated. The first free cluster found will be thenext cluster allocated, regardless of its physical locationon the disk. This permits the most efficient utilization ofdisk space because clusters made available by erasingfiles can be allocated for new files. (Refer to thedescription of the DOS File Allocation Table .)

O S isk irectory

4 4

FO RMAT initially builds the root directory for alldisks. Its location (logical sector number) and themaximum number of entries are available through the

device driver interfaces.

Since directories other than the root directory areactually files, there s no limit to the number of entriesthey may contain. Subdirectories can be read as datafiles, using an extended FCB with the appropriateattribute byte.



All directory entries are 32 bytes in length, and are inthe following format (byte offsets are in decimal):

0-7 Filename. The first byte of this field indicatesits status.

hex N ever been used. This is used tolimit the length of directorysearches, for performance reasons.

hex E5 Was used, but the file has beenerased.

hex2E

The entryis

for a directory.f

thesecond byte is also hex 2E, thenthe cluster field contains the clusternumber of this directory s parentdirectory (hex if the parentdirectory is the root directory).

Any other character is the first character of a

filename.

8-10 Filename extension.

11 File attribute. The attribute byte is mapped asfollows (values are in hexadecimal):

1 File is marked read-only. An attempt toopen the file for output using functioncall hex 3D results in an error codebeing returned. This value can be usedalong with other values below.

2 Hidden file. The file is excluded fromnormal directory searches.

4 System file. The file is excluded fromnormal directory searches.

4-5



12-21

22-23

4 6

08 The entry contains the volume label inthe first 11 bytes. The entry contains noother usable information, and may existonly in the root directory.

1 The entry defines a subdirectory, and is

excluded from normal directorysearches.

20 Archive bit. The bit is set on wheneverthe file has been written to and closed. tis used by the B CKUP andRESTORE commands for determining

whether or not thefile

was changedsince it was last backed up. This bit canbe used along with other attribute bits.

Note: The system files lBMBIO.COMand IBMDOS.COM) are marked as readonly, hidden, and system files. Files can bemarked hidden when they are created. Also,

the read-only, hidden, system, and archiveattributes may be changed through theCHMOD function call.

Reserved.

Time the file was created or last updated. Thetime is mapped in the bits as follows:

hh > < > < x x >15 14 13 12 11 10 9 8 7 5 4 3 2 1 0

where:

hh is the binary number of hours 0-23)

mm is the ~ i n r ynumber of minutes 0-59)x x is the binary number of two-second

increments

Note: The time is stored with the leastsignificant byte first.



24-25 Date the file was created or last updated. Themm/dd/yy are mapped in the bits as follows:

< 25 > < 24 >15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0

y m m m m

26-27

28-31

where:

mm is 1-12is 1-31

yy is 0-119 (1980-2099)

Note: The date is stored with the leastsignificant byte first.

Starting cluster; the cluster number of the firstcluster in the file.

Note that the first cluster for data space on allfixed disks and diskettes is always cluster002.

The cluster number is stored with the leastsignificant byte first.

Note: System programmers, seeDOS File Allocation Table for details

about converting cluster numbers tological sector numbers.

File size in bytes. The first word contains thelow-order part of the size. Both words arestored with the least significant byte first.

4 7



OS File llocation Table

4-8

This information is presented for the benefit of systemprogrammers who wish to develop device drivers. t

explains how DOS uses the File Allocation Table to

convert the clusters of a file to logical sector numbers.The driver is then responsible for locating the logicalsector on disk. We wish to emphasize that thisinformation should not be used for any other purpose.We recommend that system utilities use the DOS filemanagement function calls rather than interpreting theFAT.

The File Allocation Table FAT) is used by DOS toallocate disk space for a file, one cluster at a time.

The FAT consists of a 12-bit entry 1.5 bytes) for eachcluster on the disk.

Note that the first two F AT entries map a portion of thedirectory; these F AT entries contain indicators of thesize and format of the disk.

The second and third bytes always contain hex FFFF.The first byte is used as follows:

Hex Value Meaning

FF Dual sided, 8 sector-per-track diskette.FE Single sided, 8 sector-per-track diskette.

FD Dual sided, sector-per-track diskette.

F Single sided, 9 sector-per-track diskette.

F8 Fixed disk

The third FAT entry begins the mapping of the dataarea cluster 002).



Each entry contains three hexadecimal characters,either:

000

FFS-FFF

xxx

if the cluster is unused and available, or

to indicate the last cluster of a file, or

any other hexadecimal characters thatare the cluster number of the next

luster in the file. The cluster number ofthe first cluster in the file is kept in thefile s directory entry.

Note: The values FFO- FF7 areused to indicate reserved clustersFF7 indicates a bad cluster if it is

not part of an allocation chain),and FFS- FFF are used s

end-of-file marks.

The File Allocation Table always occupies the sector orsectors immediately following the boot record. If largerthan 1 sector, the sectors occupy consecutive numbers.Two copies of the F AT are written, one following theother, for integrity. The FAT is read into one of theDOS buffers whenever needed (open, allocate morespace, etc.), and that buffer is given a high priority tokeep it in memory as long as possible, for performance

reasons.

4 9



How to Use the File llocation Table

4-10

Obtain the st rting cluster of the file from the directoryentry.

Now, to locate each subsequent cluster of the file:

1 Multiply the cluster number just used by 1.5 eachF AT entry is 1.5 bytes long).

2. The whole part of the product is an offset into theF AT, pointing to the entry that maps the clusterjust used. That entry contains the cluster numberof the next cluster of the file.

3. Use a MOV instruction to move the word at thecalculated FAT offset into a register.

4. If the last cluster used was an even number, keepthe low-order 12 bits of the register; otherwise,

keep the high-order 12 bits.5. If the resultant 12 bits are hex FFS- FFF, there are

no more clusters in the file. Otherwise, the 12 bitscontain the cluster number of the next cluster inthe file.

To convert the cluster to a logical sector number

relative sector, such as that used by INT 25 and 26and by DEBUG :

1. Subtract 2 from the cluster number.

2. Multiply the result by the number of sectors percluster.

3. Add the logical sector number of the beginning ofthe data area.



hapter 5 OS Interrupts andFunction alls

ontents

Interrupts 5 3Function Calls 5 13

Error Return Table 5 14Invoking OS Functions 5 16

5 1



5 2



nterrupts

Note: We recommend that a program wishing toexamine or set the contents of any interrupt vectoruse the DOS function calls hex 35 and hex 25)

provided for those purposes, and avoid referencingthe interrupt vector locations directly.

DOS reserves interrupt types hex 20 to hex 3 F for itsuse. This means absolute memory locations hex 80 tohex FF are reserved by DOS. The defined interruptsare as follows with all values in hexadecimal.

20 Program terminate. Issuing Interrupt hex 20is the traditional way to exit from a program.This vector transfers to the logic in DOS forrestoration of the terminate, Ctrl-Break, andcritical error exit addreses to the values theyhad on entry to the program. All file buffersare flushed. All files changed in length should

be closed see function call hex 10 andhex 3E prior to issuing this interrupt. f thechanged file is not closed, its length, date, andtime are not recorded correctly in thedirectory.

In order for a program to pass a completionor error) code when terminating, it must use

either function call hex 4C exit) or hex 3terminate and stay resident). These two new

methods are preferred over using interrupthex 20, and the codes returned by them canbe interrogated in batch processing seeERRORLEVEL subcommand of batchprocessing).

Important: Every program must ensure thatthe CS register contains the segment addressof its Program Segment Prefix control blockprior to issuing interrupt hex 20.

5-3



5-4

2 Function request. Refer to Function Callsin this chapter.

22 Terminate address. The address found at thisinterrupt location is the address to which

control transfers when the programterminates. This address is copied into theprogram's Program Segment Prefix at thetime the segment is created. If a programwishes to execute a second program it mustset the terminate address prior to executingthe new program (unless EXEC is used).Otherwise, when the second programexecutes, its termination would cause transferto its host's termination address. Thisaddress, as well as the Ctrl-Break addressbelow, may be set via DOS function call hex25. Do not issue this interrupt directly.

23 Ctrl-Break exit address. f the user entersCtrl-Break during standard input, standardoutput, standard printer or asynchronouscommunications adapter operations, aninterrupt type hex 23 is executed. (If BREAKis on, the interrupt hex 23 is issued on

ny function call.) If the Ctrl-Break routinesaves all registers, it may end with areturn-from-interrupt instruction (IRET) tocontinue program execution. If the programreturns with a long return, the carry flag is

used to determine whether the program willbe aborted or not; if the carry flag is set, itwill be aborted, otherwise execution willcontinue (as with a return by IRET). f the



Ctrl-Break interrupts functions 9 or 10,buffered I/O then / \C carriage-return, andlinefeed are output. If execution is thencontinued with an lRET I/O continues fromthe start of the line. When the interrupt

occurs, all registers are set to the value theyhad when the original function call to DOS

was made. There are no restrictions on whatthe Ctrl-Break handler is allowed to do,including DOS function calls, as long s theregisters are unchanged if lRET is used.

f the program creates a new segment and

loads in a second p r o g r ~which itselfchanges the Ctrl-Break address, thetermination of the second program and returnto the first causes the Ctrl-Break address tobe restored to the value it had beforeexecution of the second program. It isrestored from the second program s ProgramSegment Prefix.)

24 Critical error handler vector. When a criticalerror occurs within DOS control istransferred with an interrupt 24H. On entryto the error handler, AH will have its bit 7=0(high-order bit) if the error was a disk error(probably the most common occurrence),

bit7=1

if not.

BP: SI contains the address of a DeviceHeader Control Block from which additionalinformation can be retrieved (see below).

5 5



5-6

The registers will be set up for a retryoperation, and an error code will be in thelower half of the DI register with the upperhalf undefined. These are the error codes:

Error Code Description

o Attempt to write onwrite-protected diskette

1 Unknown unit2 Drive not ready3 Unknown command4 Data error CRC)

5 Bad request structure length6 Seek error

Unknown media type8 Sector not found9 Printer out of paperA Write faultB Read faultC General failure

The user stack will be in effect the first itemdescribed below is at the top of the stack),and will contain the following from top tobottom:

IP

CSFLAGS

AXX

CXDXSIDIBPDSES

DOS registers from issuing

INT hex 24

User registers at time of originalINT hex 21 request



IPCSFLAGS

From the original interrupthex 2 from the user to DOS

The registers are set such that if an IRET isexecuted, DOS will respond according toAL) as follows:

Disk Errors

AL)=O ignore the error.

1 retry the operation.

=2 terminate the program through

interrupt hex 23.

If it is a hard error on disk AH bit 7=0), register ALcontains the failing drive number 0 drive A, etc.);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 area system files)

o 1 file allocation table1 0 directory1 1 data area

5 7



ther Errors

5 8

f AH bit 7 = 1 then the error occurred on a characterdevice or was the result of a bad memory image of theFAT. The device header passed in BP:SI can beexamined to determine which case exists. f theattribute byte high order bit indicates a block devicethen the error was a bad FAT. Otherwise the error ison a character device.

If a character device the contents of AL areunpredictable the error code is in DI as above.

Notes:

1. Before giving this routine control for diskerrors DOS performs five retries.

2. For disk errors this exit is taken only forerrors occurring during an interrupt hex 21function call. t is not used for errors during

an interrupt hex 25 or hex 26.

3. This routine is entered in a disabled state.

4. The SS SP DS ES BX ex and DXregisters must be preserved.

5. This interrupt handler should refrain fromusing DOS function calls. f necessary itmay use calls 1 through 12 . Use of any othercall will destroy the DO S stack and will leaveDOS in an unpredictable state.

6. The interrupt handler must not change thecontents of the device header.



7. f the interrupt handler will handle errorsitself rather than returning to DOS, it shouldrestore the application program s registersfrom the stack, remove all but the last 3words on the stack, then issue an IRE T. Thiswill return to the program immediately afterthe INT 2 that experienced the error Notethat if this is done, DO S will be in anunstable state until a function call higher than12 is issued.

The device header pointed to by BP: SI is

formatted as follows:

DWORD Pointer to next deviceFFFF if last device)

WORD AttributesBit 5 1 if character device, 0 if blockif bit 5 is 1

Bit 0 I if Current standard inputBit 1 = 1 if Current standard outputBit 2 1 if Current NUL deviceBit 3 1 if Current CLOCK device

Bit 14 is the IOCTL bit

WORD Pointer to Device driver strategyentry point

WORD Pointer to Device driver interruptentry point

8-BYTE character device named fieldfor block devices the first byte is

the number of units

5-9



5-10

To tell if the error occurred on a block orcharacter device you must look at bit 5 inthe attribute field WORD at BP:SI+4).

f the name of the character device is desired,look at the eight bytes starting at BP:SI+ 10

25 Absolute disk read. This transfers controldirectly to the DOS BIOS. Upon return, theoriginal flags are still on the stack put thereby the INT instruction). This is necessarybecause return information is passed back inthe current flags. Be sure to pop the stack to

prevent uncontrolled growth. The requestis

as follows:

AL)

eX)DX)DS:BX)

Drive number for example,O=A or I=B)Number of sectors to readBeginning logical sector numberTransfer address

The number of sectors specified aretransferred between the given drive and thetransfer address. ogical sector numbers areobtained by numbering each sectorsequentially starting from track 0, head 0,sector 1 logical sector 0) and continuingalong the same head, then to the next headuntil the last sector on the last head of thetrack is counted. Thus, logical sector 1 istrack 0, head 0, sector 2; logical sector 2 istrack 0, head 0, sector 3; and so on.Numbering then continues with sector 1 onhead ° f the next track. Note that althoughthe sectors are sequentially numbered for

example, sectors 2 and 3 on track°

n theexample above), they may not be physicallyadjacent on disk, due to interleaving. Notethat the mapping is different from that usedby DOS Version 1 10 for dual-sideddiskettes.



All registers except the segment registers aredestroyed by this call. If the transfer wassuccessful the carry flag CF) will be zero. f

the transfer was not successful C F = 1 andAX) will indicate the error as follows. AL)

isthe DOS error code that

isthe same as theerror code returned in the low byte of D I

when an INT hex 24 is issued, and AH) willcontain:

hex 80hex 40hex 20

hex 10hex 08hex 04hex 03

hex 02hex 00

Attachment failed to respondSEEK operation failedController failure

Bad CRC on diskette readD MA overrun on operationRequested sector not foundWrite attempt onwrite-protected disketteAddress mark not foundError other than types listedabove

26 Absolute disk write. This vector is thecounterpart of interrupt 5 above. Except forthe fact that this is a write, the descriptionabove applies.

27 Terminate but stay resident. This vector is

used by programs that are to remain residentwhen COMMAND regains control. This is

the traditional method for DOS programs toremain resident upon termination.

5-11



5-12

After initializing itself, the program must setDX to its last address plus one in the segmentin which it is executing the offset at whichother programs can be loaded), then executean INT 27H. DOS then considers the

program as an extensionof DOS

so theprogram is not overlaid when other programsare executed. This concept is very useful forloading programs such as user-writteninterrupt handlers that must remain resident.

Notes:

1 This interrupt must ot be used by.EXE programs which are loadedinto the high end of memory.

2. This interrupt restores the interrupt22, 23, and 24 vectors in the samemanner as INT 20. Therefore, itcannot be used to installpermanently resident Ctrl-Break orCritical Error Handler routines.

3 The maximum size of memory thatcan be made resident by thismethod is 64 K.

4. A new DOS function call has beenestablished that allows theterminating program to pass acompletion or error) code to DOS

that can be interpreted within batchprocessing see function callhex 31). This is the preferredmethod.



28 Used internally by DOS.

29-2E Reserved for DOS.

2F Used internally by DOS.

30-3F Reserved for DOS.

Function alls

DOS provides a wide variety of function calls for

character device I/O fil management, memory

management, date and time functions, execution ofother programs, and others. They are grouped asfollows call numbers are in hexadecimal):

0-12 Traditional character device I/O

12-24 Traditional fil management

25-26 Traditional non-device functions

27-29 Traditional fil management

2A-2E Traditional non-device functions

2F-38 Extended function group

39-3B Directory group

3C-46 Extended fil management group

47 Directory group

48-4B Extended memory management group

4C-4F Extended function group

54-57 Extended function group

5-13



Functions F through 57 are new for DOS Versions2.00 and 2.10. Where similar functions exist in boththis group and the group of traditional calls, werecommend using the new calls. They have been definedwith simpler interfaces and provide more powerful

functions than their traditional counterparts. However,if you use these new function calls your program cannotbe run on DOS Versions 1.00 or 1.10.

When DOS takes control, it switches to an internalstack. User registers are preserved unless information is

passed back to the requester as indicated in the specificrequests. The user stack needs to be sufficient to

accommodate the interrupt system. t is recommendedthat it be hex 80 in addition to the user needs.

rror Return Table

5-14

Many of the new function calls return the carry flagclear if the operation was successful. If an error

condition was encountered, the carry flag is set, andAX contains one of the following binary error returncodes:

Code Condition

1

34567

89

10

123

5

6

7

18

Invalid function numberFile not foundPath not foundToo many open files no handles left)Access deniedInvalid handleMemory control blocks destroyedInsufficient memoryInvalid memory block addressInvalid environmentInvalid formatInvalid access codeInvalid dataInvalid drive was specifiedAttempted to remove the current directoryNot same deviceNo more files



Several of the calls accept an ASCIIZ string as input.This consists of an ASCII string containing an optionaldrive specifier, followed by a directory path, and insome cases a filename. The string is terminated by abyte of binary zeros. For example:

B:\LEVEL \LEVEL2\FI LEl

followed by a byte o f zeros.

Note: All calls that accept path names will accepta forward slash or a backs lash as a path separatorcharacter.

The new calls supporting files or devices use anidentifier known as a handle. When you create oropen a fil or device with the new calls, a 16-bit binaryvalue is returned in AX. This is the handle

(sometimes known as a token) that you will use inreferring to the file after it's been opened.

The following handles are pre-defined by DOS and canbe used by your program. You do not need to openthem before using them:

0000 Standard input device. Input can beredirected.

0001 Standard output device. Output can beredirected.

0002 Standard error output device. Output cannotbe redirected.

0003 Standard auxiliary device.

0004 Standard printer device.

5-15



Invoking OS unctions

5-16

Most of the function calls require input to be passed tothem in registers. After setting the proper registervalues, the function may be invoked in one of these

ways:1 Place the function number in AH and execute a

long call to offset hex 50 in your Program SegmentPrefix. Note that programs using this method willnot operate correctly on DOS Veri sons 1.00 andl 10

2 Place the function number in AH and issueinterrupt type hex 21.

3 There is an additional mechanism provided forpre-existing programs that were written withdifferent calling conventions. This method shouldbe avoided for all new programs. The functionnumber is placed in the CL register and otherregisters are set according to the functionspecification. Then an intrasegment call is made tolocation 5 in the current code segment. Thatlocation contains a long call to the DOS functiondispatcher. Register AX is always destroyed if thismechanism is used; otherwise, it is the same asnormal function calls. This method is valid onlyfor function calls 0-24 hexadecimal).



The functions are as follows with all values inhexadecimal.

o Program terminate. The terminate, Ctrl-Break, andcritical error exit addresses are restored to the

values they had on entryto

the terminatingprogram, from the values saved in the ProgramSegment Prefix. All file buffers are flushed, butany files which have been changed in length butnot closed will not be recorded properly in thedirectory. Control transfers to the terminateaddress. This call performs exactly the samefunction as INT 20H. t s the program s

responsibility to ensure that the CS registercontains the segment address of its ProgramSegment Prefix control block prior to calling thisfunction.

Note: Calls hex 1 through hex C use thestandard devices listed at the end of the

Error Return Table in this chapter.

Keyboard input. Waits for a character to be readat the standard input device (unless one s ready),then echoes the character to the standard outputdevice and returns it in AL. The character s

checked for a Ctrl-Break. I f Ctrl-Break s detected,an interrupt hex 23 s executed.

Note: For functions 1, 6, 7, and 8,extended ASCII codes will require twofunction calls. (See the IBM PersonalComputer B SIC manual for a description of

the extended ASCII codes.) The first callreturns 00 as an indicator that the next callwill return an extended code.

5-17



5 18

2 Display output. The character in D L is output tothe standard output device. The backspacecharacter results in moving the cursor left oneposition, writing a space at this position andremaining there. f a Ctrl-Break is detected after

the output, an interrupt hex 23 is executed.

3 Auxiliary Asynchronous CommunicationsAdapter) input. Waits for a character from thestandard auxiliary device, then returns thatcharacter in AL.

Notes:

1 Auxiliary AUX, COM1, COM2)support is unbuffered and non-interruptdriven.

2. At startup, DOS initializes the firstauxiliary port to 2400 baud, no parity,one stop bit, and 8-bit word.

3 The auxiliary function calls 3 and 4) donot return status or error codes. Forgreater control, it is recommended thatthe ROM BIOS routine INT hex 14)be used.

4 Auxiliary Asynchronous CommunicationsAdapter) output. The character in D L is output tothe standard auxiliary device.

5 Printer output. The character in D L is output tothe standard printer device.



6 Direct console I/O. If DL is hex FF AL returnswith the zero flag clear and an input characterfrom the standard input device if one is ready. f acharacter is not ready, the zero flag will be set. f

DL is not hex FF then DL is assumed to have avalid character that is output to the standardoutput device. This function does not check forCtrl-Break, or Ctrl-PrtSc.

7 Direct console input without echo. Waits for acharacter to be read at the standard input device(unless one is ready), then returns the character inAL. As with function 6, no checks are made on the

character.

8 Console input without echo. This function isidentical to function 1 except the key is notechoed.

9 Print string. On entry, DS:DX must point to acharacter string in memory terminated by a(hex 24). Each character in the string will beoutput to the standard output device in the sameform as function 2.

A Buffered keyboard input. On entry, DS:DX pointto an input buffer. The first byte must not be zeroand specifies the number of characters the buffercan hold. Characters are read from the standardinput device and placed in the buffer beginning atthe third byte. Reading the standard input deviceand filling the buffer continues until Enter is read.

f the buffer fills to one less than the maximumnumber of characters it can hold, then eachadditional character read is ignored and causes thebell to ring, until Enter is read. The second byte of

the buffer is set to the number of charactersreceived, excluding the carriage return (hex OD),which is always the last character.

5-19



5-20

B Check standard input status. If a character isavailable from the standard input device, AL willbe hex FF. Otherwise, AL will be 00. If aCtrl-Break is detected, an interrupt type hex 23 isexecuted.

C Clear keyboard buffer and invoke a keyboardfunction. Clear the keyboard buffer of anypre-typed characters, then execute the functionnumber in AL only 1 6, 7, 8, and A are allowed).This forces the system to wait until a character istyped.

D Disk reset. Flushes all file buffers. FHes changedin size but not closed are not properly recorded inthe disk directory. This function need not be calledbefore a diskette change if all files written havebeen closed.

E Select disk. The drive specified in DL O=A,1=B, etc.) is selected if valid) as the default drive.

The number of drives total of diskette and fixeddisk drives) is returned in AL. If the system hasonly one diskette drive, it will be counted as two tobe consistent with the philosophy of thinking of thesystem as having logical drives A and B. BIOSequipment determination INT 11 H can be usedas an alternative method, returning the actualnumber of physical diskette drives.



F Open file. On entry, DS:DX point to an unopenedfile control block FCB). The current directory issearched for the named file and AL returnshex FF if it is not found. f it is found, AL returns00 and the FCB is filled as follows:

If the drive code was 0 default drive), it ischanged to the actual drive used 1 A, 2= Betc.). This allows changing the default drivewithout interfering with subsequent operations onthis file. The current block field FCB bytes C-D)is set to zero. The size of the record to be workedwith FCB bytes E-F is set to the system defaultof

hex 80. The sizeof

the file and the date are setin the FCB from information obtained from thedirectory.

t is your responsibility to set the record size FCBbytes E-F to the size you wish to think of the filein terms of, if the default hex 80 is insufficient. t

is also your responsibility to set the random record

field and/or current record field. These actionsshould be done after open but before any diskoperations are requested.

10 Close file. This function must be called after filewrites to ensure all directory information isupdated. On entry, DS:DX point to an openedFCB. The current disk directory is searched and ifthe file is found, its position is compared with thatkept in the FCB. If the file is not found in itscorrect position in the current directory, it isassumed the diskette was changed and AL returnshex FF. Otherwise, the directory is updated toreflect the status in the FCB and AL returns 00.

5-21



5-22

11 Search for the first entry. On entry, DS:DX pointto an unopened FCB. The current disk directory issearched for the first matching filename namecould have ? s indicating any letter matches) andif none are found, AL returns hex FF. Otherwise,AL returns 00 and the locations at the disktransfer address are set as follows:

If the FCB provided for searching was anextended FCB, then the first byte at the disktransfer address is set to hex FF, followed byfive bytes of zeros, then the attribute bytefrom the search FCB, then the drive number

used 1 =A, 2=B, etc.), then the 32 bytes ofthe directory entry. Thus, the disk transferaddress contains a valid unopened extendedFCB with the same search attributes as thesearch FCB.

If the FCB provided for searching was a normalFCB, then the first byte is set to the drive number

used 1 =A, 2=B), and the next 32 bytes containthe matching directory entry. Thus, the disktransfer address contains a valid unopened normalFCB.

Notes:

If an extended FCB is used, the followingsearch pattern is used:

1. f he FCB attribute byte is zero, onlynormal file entries are found. Entries forvolume label, sub-directories, hiddenand system files, will not be returned.



2 If the attribute field is set for hidden orsystem files, or directory entries, it is tobe considered as an inclusive search. Allnormal file entries plus all entriesmatching the specified attributes are

returned. To look at all directory entriesexcept the volume label, the attributebyte may be set to hidden systemdirectory (all 3 bits on).

3 If the attribute field is set for the volumelabel, it is considered an exclusivesearch, and on y the volume label entryis returned.

The attribute bits are defined in the DOS DiskDirectory section of Chapter 4 of this manual.

12 Search for the next entry. After function 11 hasbeen called and found a match, function 12 may becalled to find the next match to an ambiguousrequest (?s in the search filename). Both inputs andoutputs are the same as function 11. The reservedarea of the FCB keeps information necessary forcontinuing the search, so no disk operations maybe performed with this FCB between a previousfunction 11 or 12 call and this one.

13Delete file. On entry,

DS:DXpoint to anunopened FCB. All matching current directory

entries are deleted. If no directory entries match,AL returns hex FF, otherwise AL returns 00.

5-23



5-24

14 Sequential read. On entry, DS:DX point to anopened FCB. The record addressed by the currentblock (FCB bytes C-D) and the current record(FCB byte 1 F is loaded at the disk transferaddress, then the record address is incremented.(The length of the record is determined by theFCB record size field.) f end-of-file isencountered, AL returns either 1 or 03. A returnof 1 indicates no data in the record; 03 indicatesa partial record is read and filled out with zeros. Areturn of 02 means there was not enough space inthe disk transfer segment to read one record, so thetransfer was ended. AL returns 00 if the transfer

was completed successfully.

15 Sequential write. On entry, DS:DX point to anopened FCB. The record addressed by the currentblock and current record fields (size determined bythe FCB record size field) is written from the disktransfer address (or, in the case of records lessthan sector sizes, is buffered up for an eventualwrite when a sector s worth of data is

accumulated). The record address is thenincremented. f the diskette is full, AL returns 01.A return of 02 means there was not enough spacein the disk transfer segment to write one record, sothe transfer was ended. AL returns 00 if thetransfer was completed successfully.

16 Create file. On entry, DS:DX point to anunopened FCB. The current disk directory is

searched for a matching entry, and if found, it is

re-used. f no match was found, the directory issearched for an empty entry, and AL returns FF ifnone is found. Otherwise, the entry is initialized toa zero-length file, the file is opened (see function

F , and AL returns 00.

The file may be marked hi en during its creationby using an extended FCB containing theappropriate attribute byte.



7 Rename file. On entry, DS:DX point to a modifiedFCB which has a drive code and a file name in theusual position, and a second file name starting6 bytes after the first (DS:DX+hex 11) in what is

normally a reserved area. Every matching

occurrence of the first namein

the currentdirectory is changed to the second with therestriction that two files cannot have the samename and extension). If ? s appear in the secondname, then the corresponding positions in theoriginal name will be unchanged. AL returns FF ifno match was found or if an attempt was made torename to a filename that already existed,

otherwise 00.


19 Current disk. AL returns with the code of thecurrent default drive (0= A, 1 = B, etc.).

1A Set disk transfer address. The disk transfer addressis set to DS:DX. DOS does not allow disktransfers to wrap around within the segment, or

overflow into the next segment.

1B Allocation table information. On return, DS:BXpoint to a byte containing the FAT identificationbyte for the default drive, DX has the number of

allocation units, AL has the number of sectors perallocation unit, and CX has the size of thephysical sector.

Note: With DOS Versions 2.00 and 2.10,this call no longer returns the address of acomplete File Allocation Table, because theFAT's are no longer kept resident in memory.

5 25



5-26

1C Allocation table information for specific drive.This call is identical to call hex 1 B except that onentry, D L contains the number of the drive fromwhich the information should be gotten0 = default, 1 = A, etc.).

1D Used internally by DOS

1E Used internally by DOS

1F Used internally by DOS

20 Used internally by DOS

21 Random read. On entry, DS:DX point to anopened FCB. The current block and current recordfields are set to agree with the random record field,then the record addressed by these fields is readinto memory at the current disk transfer address. I f

end-of-file is encountered, AL returns either 1 or03. I f 1 is returned, no more data is available. f

03 is returned, a partial record is available filledout with zeros. A return of 02 means there was notenough space in the disk transfer segment to readone record, so the transfer was ended. AL returns00 if the transfer was completed successfully.

22 Random write. On entry, DS:DX point to anopened FCB. The current block and current recordfields are set to agree with the random record field,then the record addressed by these fields is writtenor in the case of records not the same as sector

sizes - buffered) from the disk transfer address. I f

the disk is full AL returns 01. A return of 02

means there was not enough space in the disktransfer segment to write one record; so, the

transfer was ended. AL returns 00 if the transferwas completed successfully.



23 File size. On entry, DS:DX point to an unopenedFCB. The current directory is searched for the firstmatching entry and if none is found, AL returnsFF Otherwise, the random record field is set tothe number of records in the file in terms of therecord size field rounded up) and AL returns 00.

Note: Be sure to set the FCB record sizefield before using this function call; otherwise,erroneous information will be returned.

24 Set random record field. On entry, DS:DX pointto an opened FCB. This function sets the randomrecord field to the same file address as the currentblock and record fields.

25 Set interrupt vector. The interrupt vector table forthe interrupt type specified in AL is set to the4-byte address contained in DS:DX Note that theoriginal contents of the interrupt vector can beobtained through call hex 35.

26 Create a new program segment. On entry, D X hasa segment number at which to set up a newprogram segment. The entire hex 100 area atlocation zero in the current program segment is

copied into location zero in the new programsegment. The memory size information at location6 in the new segment is updated and the current

termination, Ctrl-Break exit and critical erroraddresses from interrupt vector table entries forinterrupt types 22, 23, and 24 are saved in the newprogram segment starting at hex OA They arerestored from this area when the programterminates.

Note: Use of this call should be avoided,now that DOS contains the EXEC functioncall hex 4B).

5-27



5-28

27 Random block read. On entry, D S:D X point to anopened FeB and e x contains a record count thatmust not be zero. The specified number of recordsin terms of the record size field) are read from the

file address specified by the random record fieldinto the disk transfer address. If end-of-file is

reached before all records have been read, AL

returns either 01 or 03. A return of 01 indicatesend-of-file and the last record is complete. Areturn of 03 indicates the last record is a partialrecord. If wrap-around above address hex FFFFin the disk transfer segment would have occurred,as many records as possible are read and AL

returns 02. If all records are read successfully, AL

returns 00. In any case, e x returns with the actualnum er of records read, and the random recordfield and the current block/record fields are set toaddress the next record the first record not read).

28 Random block write. Essentially the same asfunction 27 above, except for writing and a

write-protect check. f there is insufficient space onthe disk, AL returns Oland no records are written.If e x is zero upon entry, no records are written,but the file is set to the length specified by therandom record field, whether longer or shorter thanthe current file size. Allocation units are releasedor allocated as appropriate.)

29 Parse filename. On entry, DS:SI point to acommand line to parse, and ES DI point to aportion of memory to be filled with an unopenedFeB. The contents of AL are used to determinethe action to take, as shown below:

< ignored>bit: 7 6 5 4 3 2 1 0

If bit 0 = 1 then leading separators are scannedoff the command line at DS:SI. Otherwise, noscan-off of leading separators takes place.



If bit 1 = 1, then the drive ID byte in the resultFCB will be set changed) on y if a drive wasspecified in the command line being parsed.

f bit 2 = 1 then the filename in the FCB will bechanged only if the command line contains afilename.

f bit 3 = I , then the filename extension in theFCB will be changed only if the command linecontains a filename extension.

Filename separators include the followingcharacters:

. ;=

+ plus TAB andSPACE.

Filename terminators include all of thesecharacters plus \ < > I, /, , [, ], and anycontrol characters.

The command line is parsed for a filename of theform d:filename.ext, and if found, a correspondingunopened FCB is created at ES:DI. If no drive

specifier is present, the default drive is assumed. Ifno extension is present, it is assumed to be allblanks. If the character appears in the filenameor extension, then it and all remaining charactersin the name or extension are set to ?

If either? or appears in the filename or

extension, AL returns 01; if the drive specifier isinvalid AL returns FF; otherwise 00.

DS:SI will return pointing to the first characterafter the filename and ES:DI will point to the firstbyte of the formatted FCB. If no valid filename ispresent, ES:DI 1 will contain a blank.

Note:This call is not useful for commandlines containing path names.

5-29



2F Get DTA. On return, ES:BX contains the currentDT A transfer address.

30 Get DOS version number. On return, AL containsthe major version number. AH contains the minor

version number. On return, BX and CX are set tozero.

Note: If AL returns zero, it can be assumedthat i t is a pre-DOS Version 2.00 system.

31 Terminate process and remain resident KEEP

process). On entry, AL contains a binary exitcode. DX contains the memory size value inparagraphs. This function call terminates thecurrent process and attempts to set the initialallocation block to the number of paragraphs inDX. t will not free up any other allocation blocksbelonging to that process. The exit code passed inAL is retrievable by the parent through Waitfunction call hex 4 D) and can be tested through

the ERRORLEVEL batch subcommands.


33 Ctrl-Break check. On entry, AL contain.s 00 torequest the current state of Control-Break

checking,1

to set the state.f

setting the state,DL must contain 00 for OFF or 1 for ON. DLreturns the current state 00 = OFF, 1 = ON).


35 Get vector. On entry, AL contains a hexadecimalinterrupt number. The CS:IP interrupt vector for

the specified interrupt is returned in ES:BX. Notethat interrupt vectors can be set through call hex25.

5-31



5 32

36 Get disk free space. On entry, DL contains adrive: 0 = default, 1 = A, etc. On return, AX

returns F F F F if the drive number was invalid.Otherwise, BX contains the number of availableallocation units clusters), D X contains the total

number of clusters on the drive, ex contains thenumber of bytes per sector, and AX contains thenumber of sectors per cluster.

N ate: This call returns the sameinformation in the same registers except forthe FAT pointer) s the get FAT pointer callhex 1 B) did in previous versions of DOS


38 Return country dependent informationinternational). On entry, DS:DX points to a

32-byte block of memory in which returnedinformation is passed and AL contains a functioncode. In DOS 2.00 and 2.10, this function codemust be zero. The following information is

pertinent to international applications:

i WORD Date/tim;iormat 11 1

; YTE ASCIIZ string ;I currency symbol II followed by byte of zeros Ir II YTE ASCIIZstring II thousands separator II followed by byte of zeros I- - - - - - - - - - - - - - 1

; YTE ASCIIZ string decimal ;I separator II followed by byte of zeros I

1 - - - - - - - - - - - - - - - 1I . 4 bytes II Reserved I_ _ _ _ _ _ _ _ _ _ _ J



The date and time format has the following valuesand meaning:

= USA standard h m s ml ly

1 = Europe standard h m s imly

= Japan standard h m s d m y

39 Create a subdirectory MKDIR). On entry,DS:DX contains the address of an ASCIIZ stringwith drive and directory path names. If anymember of the directory path does not exist, then

the directory pathis

not changed. On return, a newdirectory is created at the end of the specified path.Error returns are 3 and 5 refer to error returntable).

3A Remove a directory entry RMDIR). On entry,DS:DX contains the address of an ASCIIZ stringwith the drive and directory path names. The

specified directory is removed from the structure.The current directory cannot be removed. Errorreturns are 3 and 5 refer to error return table).Note that code 5 is returned if the specifieddirectory is not empty.

B Change the current directory CHDIR). On entry,DS:DX contains the address of an ASCIIZ stringwith drive and directory path names. If anymember of the directory path does not exist, thenthe directory path is not changed. Otherwise, thecurrent directory is set to the ASCIIZ string. Errorreturn is 3 refer to the error return table).

5-33



5-34

3C Create a file CREAT). On entry, DS:DXcontains the address of an ASCIIZ string with thedrive, path, and filename. CX contains theattribute of the file. This function call creates anew file or truncates an old file to zero length inpreparation for writing. f the file did not exist,then the file is created in the appropriate directoryand the fil is given the read/write access code.The file is opened for read/write, and the handle is

returned in AX. Error returns are 3, 4, and 5(refer to the error return table). If an error code of5 is returned, either the directory was full or a fileby the same name exists and is marked read-only.Note that the change mode function call (hex 43)can later be used to change the file s attribute.

3D Open a file. On entry, DS:DX contains theaddress of an ASCIIZ string with the drive, path,and filenames. AL contains the access code. Onreturn, AX contains an error code or a 16-bit filehandle associated with the file. The following

access codes are allowed in AL:

AL = 0 - file is opened for reading.

AL = 1 file is opened for writing.

AL = 2 - file is opened for both readingand writing.



The read/write pointer is set at the first byte of thefile and the record size of the file is 1 byte (theread/write pointer can be changed through functioncall hex 42). The returned file handle must be usedfor subsequent input and output to the file. The

file's date and time can be obtained or set throughcall hex 57, and its attribute can be obtainedthrough call hex 43. Error returns are 2, 4, 5, and12 (refer to the error return table).

Note: This call will open any normal orhidden file whose name matches the namespecified.

3E Close a file handle. On entry, BX contains the filehandle that was returned by open. On return,the file will be closed and all internal buffers areflushed. Error return is 6 (refer to the error returntable .

3F Read from a file or device. On entry, BX containsthe file handle. CX contains the number of bytesto read. DS:DX contains the buffer address. Onreturn, AX contains the number of bytes read. f

the value is zero, then the program has tried toread from the end of file. This function calltransfers (CX) bytes from a file into a bufferlocation. t is not guaranteed that all bytes will be

read. For example, reading from the keyboard willread at most one line of text. f his read isperformed from the standard input device, theinput can be redirected (see Redirection ofStandard Input and Output in Chapter 1 of DiskOperating System Reference manual). Errorreturns are 5 and 6 (refer to the error return table).

5 35



5-36

40 Write to a file or device. On entry, BX containsthe file handle. CX contains the number of bytesto write. DS DX contains the address of the datato write. Write transfers (CX) bytes from a bufferinto a file. AX returns the number of bytes

actually written.If

this valueis

not the sameas

thenumber requested, it should be considered an error(no error code is returned, but your program cancompare these values). The usual reason for this is

a full disk. If this write is performed to thestandard output device, the output can beredirected (see Redirection of Standard Input andOutput in Chapter 1 of the Disk Operating

System Reference manual). Error returns are 5and 6 (refer to the error return table).

41 Delete a file from a specified directory (Unlink).On entry, DS DX contains the address of anASCIIZ string with a drive, path, and filename.Global filename characters are not allowed in anypart of the string. This function call removes adirectory entry associated with a filename. Readonly files cannot be deleted by this call. To deleteone of these files, you can first use call hex 43 tochange the file's attribute to 0, then delete the file

Error returns are 2 and 5 (refer to the error returntable).



5 38

44 I/O control for devices lOCTL). On entry, ALcontains the function value. BX contains the file

handle. On return, AX contains the number ofbytes transferred for functions 2, 3, 4, and 5 orstatus (00 = not ready, FF = ready) for functions

6 and 7, or an error code. Use IOCTL to Set orGet device information associated with opendevice handle, or send/receive control strings tothe device handle. The following function valuesare allowed in AL:

AL = 0 - Get device information (returnedin DX).

AL = 1 - Set device information (determinedby DX). Currently, DR must bezero for this call.

AL = 2 - Read CX number of bytes intoDS:DX from device controlchannel.

AL = 3 - Write CX number of bytes fromDS:DX to device control channel.

AL = 4 - Same s 2, but use drive number inBL (0 = default, 1 = A, etc.).

AL = 5 - Same s 3, but use drive number inBL (0 = default, 1 = A, etc.).

AL = 6 -Get input status.

AL = 7 - Get output status.

IOCTL can be used to get information about

device channels. You can make calls on regularfiles, but only function values 0, 6, and 7 aredefined in that case. All other calls return an

invalid function error.



IT

RES

alls AL=O and A L = l The bits o f D X aredefined as follows:

eserved

ISDEV = 1 if this channel is a device.

f ISDEV = 1

of this channel

isa disk filebits 8-15 = 0 in this case).

EOF = if end-of-file on input.BIN = 1 if operating in binary mode

no checks for Ctrl-Z).= if operating in ASCII mode

checking for Ctrl-Z asend-of-file).

ISCLK = 1 if this device is the clockdevice.

ISNUL = 1 if this device is the nulldevice.

ISCOT = 1 if this device is the consoleoutput.

ISCIN = 1 if this device is the consoleinput.

CTRL = 0 if this device cannot processcontrol strings via calls A L = 2

and AL=3

CTRL = 1 if this device can processcontrol strings via calls AL= 2

andA L = 3 Note

that this bitcannot be set by function callhex 44.

o

5-39



5 40

If ISDEV = 0EOF = 0 if channel has been written.

Bits 0-5 are the block devicenumber for the channel(0 = A, 1 = B, ... .

Bits 1 5, 8-13, 4 are reserved and should not bealtered.

Note: D H must be zero for call AL= 1.

alls AL=2 AL=3 AL=4 AL=5. These fourcalls allow arbitrary control strings to be sent orreceived from a character device. The Call syntaxis the same as the Read and Write calls, except forcalls 4 and 5 which accept a drive number in BLinstead of a handle in BX. An invalid functionerror is returned if the CTRL bit is zero. An

access-denied code is returned by calls 4 and 5if the drive is invalid. Error returns are 1, 6, and13 (refer to the error return table).

alls 6 and 7. These calls allow you to check if afile handle is ready for input or output. I f used fora file, AL always returns FF until end-of-file isreached, then always returns unless the currentfile position is changed through call hex 42. Whenused for a device, AL returns FF for ready or zerofor not ready.

45 Duplicate a file handle (DUP). On entry, BX

contains the file handle. On return, AX containsthe returned file handle. This function call takes anopened file handle and returns a new file handlethat refers to the same file at the same position.Error returns are 4 and 6 (refer to the error returntable .

Note: f you move the read/write pointer of

either handle, the pointer for the other handlewill also be changed.



46 Force a duplicate of a handle DUP). On entry,BX contains the file handle. CX contains a secondfile handle. On return, the CX file handle will referto the same stream s the BX file handle. If theCX file handle was an open file, then t is closedfirst. Error return is 6 refer to the error returntable).

Note: f you move the read/write pointer ofeither handle, the pointer for the other handlewill also be changed.

47 Get Current directory. On entry, D L contains adrive number 0 = default, 1 = A, etc.) and DS:SIpoint to a 64-byte area of user memory. The fullpath name starting from the root directory) of thecurrent directory for the specified drive is placed inthe area pointed to by DS:SI. Note that the driveletter will not be part of the returned string. Thestring will not begin with a backslash and will beterminated by a byte containing hex 00. The error

returned is 15.

48 Allocate memory. On entry, BX contains thenumber of paragraphs requested. On return, AX:Opoints to the allocated memory block. f theallocation fails, BX will return the size of thelargest block of memory available in paragraphs.Error returns are 7 and 8 refer to the error returntable).

49 Free allocated memory. On entry, ES contains thesegment of the block being returned. On return, ablock of memory is returned to the system poolthat was allocated by call hex 48. Error returns are7 and 9 refer to the error return table).

5 41



5-42

4A SETBLOCK-Modify allocated memory blocks.On entry, E S contains the segment of the block.BX contains the new requested block size inparagraphs. DOS will attempt to grow orshrink the specified block. If the call fails on a

grow request, then on return, BX contains themaximum block size possible. Error returns are 7,8, and 9 (refer to the error return table).

4B Load or execute a program EXEC). This functioncall allows a program to load another program intomemory and ( default) begin execution of it.DS:DX points to the ASCIIZ string with drive,path, and filename of the file to be loaded. ES:BXpoints to a parameter block for the load and ALcontains a function value. The following functionvalues are allowed:

o Load and execute the program. Aprogram segment prefix s established forthe program and the terminate and

control-break addresses are set to theinstruction after the EXEC system call.

Note: When control s returned, allregisters are changed including the stack.You must restore SS, SP and any otherrequired registers before proceeding.

3 Load, do not create the programsegment prefix, and do not beginexecution. This s useful n loadingprogram overlays.



For each of these values the block pointed to byES:BX has the following format:

L = 0 Load execute program

WORD segment address of environment stringto be passed

DWORD pointer to command line to be placedat PSP 80h

DWORD points to default FCB to be passed atPSP 5Ch

DWORD pointer to default FCB to be passedat PS P 6Ch

L = 3 Load overlay

WORD segment address where file will beloaded

WORD relocation factor to be applied to the

image

Note that all open files of a process are duplicatedin the newly created process after an EXEC. Thisis extremely powerful; the parent process hascontrol over the meanings of standard inputoutput auxiliary and printer devices. The parent

could for example write a series of records to afile open the file as standard input open a listingfile s standard output and then execute a sortprogram that takes its input from standard inputand writes to standard output.

5-43



5-44

Also inherited (or copied from the parent) is anenvironment. This is a block of text strings (less

than 32K bytes total) that convey variousconfiguration parameters. The following is theformat of the environment (always on a paragraph

boundary):

Byte ASCIIZ string 1

Byte ASCIIZ string 2

Byte ASCIIZ string n

Byte of zero

Typically the environment strings have the form:

parameter value

For example, the string VERIFY=ON could bepassed. A zero value of the environment addresswill cause the newly created process to inherit theparent's environment unchanged. The segmentaddress of the environment is placed at offset hex2C of the Program Segment Prefix for the programbeing invoked. Error returns are 1, 2, 5 8, 10, and11 (refer to the error return table).

Notes:

1 When your program received control, all of

available memory was allocated to it. You

must free some memory (see call hex 4A)before EXEC can load the program you areinvoking. Normally, you would shrink downto the minimum amount of memory you need,and free the rest.



2. The EXEC call uses the loader portion of

COMMAND.COM to perform the loading.I f your program has overlaid the loader, thiscall will attempt to re-Ioad the loader. If youhave used t h e Allocate Memory call to

allocate all of memory and the loader hasbeen overlaid, the EX EC call will return anerror due to insufficient memory to load theloader.

4C Terminate a process (Exit). On entry, AL containsa binary return code. This function call willterminate the current process, transferring controlto the invoking process. In addition, a return codecan be sent. The return code can be interrogatedby the batch subcommands IF andERRORLEVEL and by the wait function call(4D). All files opened by the call 3D are closed.

4D Retrieve the return code of a sub-process (Wait).This function call returns the Exit code specifiedby another process (via call hex 4C or call hex 31)in AX. t returns the Exit code only once. The lowbyte of this code is that sent by the exiting routine.The high byte is zero for normal termination, 1 ifterminated by Crtl-Break, 02 if terminated as theresult of a critical device error, or 03 if terminatedby function call hex 31.

5-45



5-46

4E Find first matching file FIND FIRST). On input,DS:DX points to an ASCIIZ string containing thedrive, path, and filename of the file to be found.The filename portion can contain global filenamecharacters. CX contains the attribute to be used in

searching for the file. See function call hex for adescription of how the attribute bits are used forsearches. If a file is found that matches thespecified drive, path, and filename and attribute,the current DT A will be filled in as follows:

2 bytes - reserved for DOS use onsubsequent find next calls

1 byte - attribute found

2 bytes - file s time

2 bytes - file s date

2 bytes - low word of file size

2 bytes - high word of file size

3 bytes - name and extension of file found,followed by a byte of zeros. All blanks areremoved from the name and extension, and ifan extension is present, it is preceded by a

period. Thus, the name returned appears justas you would enter it as a commandparameter. Such as, TREE.COM followedby a byte of zeros. Error returns are 2 and 1 8(refer to the error return table).



4F Find next matching file. On input, the currentDT A must contain the information that was filledin by a previous Find First call hex 4E). No otherinput is required. This call will find the nextdirectory entry matching the name that wasspecified on the previous Find First call. If amatching file is found, the current DT A will be setas described in call hex 4E. f no more matchingfiles are found, error code 18 is returned refer tothe error return table).





54 Get verify state. On return, AL returns 00 ifverify is OFF 1 if verify is ON. Note that the

verify switch can be set through call hex 2E.


56 Rename a file. On input, DS:DX points to anASCIIZ string containing the drive, path, andfilename of the file to be renamed. ES:DI points toan ASCIIZ string containing the path and filenameto which the file is to be renamed. If a drive is usedin this string, it must be the same as the drivespecified or implied in the first string. Thedirectory paths need not be the same, allowing afile to be moved to another directory and renamedin the process. Error returns are 3, 5, and 17 referto the error return table).

5-47



5-48

57 Get/Set a file s date and time. On input, AL

contains 00 or 01. BX contains a file handle. f

AL=OO on entry, D X and CX will return the dateand time from the handle s internal table,respectively. If AL=Ol on entry, the handle s dateand time will be set to the date and time in D Xand CX respectively. The date and time formatsare the same as those for the directory entrydescribed in Chapter 4 of this manual, except thatwhen passed in registers, the bytes are reversed(that is, DR contains the ow order portion of thedate, etc.). Error returns are 1 and 6 (refer to theerror return table).



Chapter 6 OS Control Blocksand Work Areas

Contents

DOS Memory Map 6 3DOS Program Segment 6 5Program Segment Prefix 6 9File Control Block . . . . . . . . . . . . . . . . . . . . . . 6 11

Standard File Control Block 6 12Extended File Control Block 6 15

6 1



OS emory ap

0000:0000 Interrupt vector table

0040:0000 RO M communication area

0050:0000 DOS communication area

XXXX:OOOO IBMBIO.COM - DOS interface to ROMI/O routines

XXXX:OOOO IBMDOS.COM - DOS interrupt handlers,

service routines INT 2 functions)

DOS buffers, control areas, and installeddevice drivers

XXXX:OOOO Resident portion of COMMAND. COM -Interrupt handlers for interruptshex 22 terminate), hex 23 Ctrl-Break),hex 24 critical error), and code to reloadthe transient portion.

XXXX:OOOO External command or utility - .COM or.EXE file)

XXXX:OOOO User stack for .COM files 256 bytes)

XXXX:OOOO Transient portion of COMMAND.COM -Command interpreter, internal commands,batch processor, external command loader.

6-3



6-4

Notes:

1 Memory map addresses are in segment:offsetformat. For example 0070:0000 is absoluteaddress hex 0700.

2 The DOS Communication Area is used asfollows:

0050:0000 Print screen status flag store

o Print screen not active orsuccessful print screenoperation

1 Print screen in progress

255 Error encountered duringprint screen operation

0050:0001 Used by BASIC

0050:0004 Single-drive mode status byte

o Diskette for drive A waslast used

1 Diskette for drive B waslast used

0050:0010 - 0021 Used by BASIC

0050:0022 - 2F Used by DOS fordiskette initialization

0050:0030 - 0033 Used by MODE

command

All other locations within the 256 bytesbeginning at 0050:0000 are reserved forDOS use.



3 User memory is allocated from the lowestend of available memory that will satisfy therequest for memory.

OS rogram Segment

When you enter an external command, or invoke aprogram through the EXEC function call, DOS

determines the lowest available address to use as thestart of available memory for the program beinginvoked. This area is called the Program Segment

Atoffset 0 within the Program Segment,

DOSbuildsthe Program Segment Prefix control block. See below.)

EXEC loads the program at offset hex 100 and gives itcontrol.

The program returns from EXEC by a jump to offset 0in the Program Segment Prefix, by issuing an INT 20,by issuing an INT 21 with register AH=O or hex 4C, or

by calling location hex 5 in the Program SegmentPrefix with AH=O or hex 4C.

Note: t is the responsibility of all programs toensure that the CS register contains the segmentaddress of the Program Segment Prefix whenterminating via any of these methods except callhex 4C.

6-5



6 6

All of these methods result in returning to the programthat issued the EXEC. During this returning processinterrupt vectors hex 22, hex 23, and hex 24 terminate,Ctrl-Break, and critical error exit addresses) arerestored from the values saved in the Program SegmentPrefix of the terminating program. Control is then givento the terminate address. f this is a program returningto COMMAND control transfers to its transientportion. If a batch fil was in process, it is continued;otherwise, COMMAND issues the system prompt andwaits for the next command to be entered from thestandard input device.

When a program receives control, the followingconditions are in effect:

F or all programs:

• The segment address of the passed environment is

contained at offset hex 2C in the Program SegmentPrefix.

The environment is a series of ASCII stringstotaling less than 32K) in the form:

NAME parameter

Each string is terminated by a byte of zeros, andthe entire set of strings is terminated by another

byte of zeros. The environment built by thecommand processor and passed to all programs itinvokes) will contain a COMSPEC= string at aminimum the parameter on COMSPEC is thepath used by DO S to locate the commandprocessor on disk). The last PATH and PROMPT

commands issued will also be in the environment,along with any environment strings enteredthrough the SET command see Chapter 2 of theDOS eference manual).



The environment that you are passed is actually acopy of the invoking process environment. If yourapplication uses a terminate and stay residentconcept, you should be aware that the copy of theenvironment passed to you is static. That is, your

copy of the environment will not change even ifsubsequent SET, PATH, or PROMPT commandsare issued.

• Offset hex 50 in the Program Segment Prefixcontains code to invoke the DOS functiondispatcher. Thus, by placing the desired functionnumber in AH, a program can issue a long call to

PSP+ 50 to invoke a DOS function, rather thanissuing an interrupt type hex 21.

• Disk transfer address DTA) is set to hex 80(default DTA in the Program Segment Prefix).

• File control blocks at hex 5C and hex 6C areformatted from the first two parameters enteredwhen the command was invoked. Note that ifeither parameter contained a path name, then thecorresponding FCB will contain only a valid drivenumber. The filename field will not be valid.

• An Unformatted parameter area at hex 8

contains all the characters entered after thecommand name (including leading and imbeddeddelimiters). with hex 80 set to the number ofcharacters. f the > , o r : r m e t e r ~wereentered on the command line, they (and thefilenames associated with them) will not appear inthis area, because redirection of standard input andoutput is transparent to applications.

• Offset 6 (one word) contains the number of bytesavailable in the segment.

6-7



6 8

• Register AX reflects the validity of drive specifiersentered with the first two parameters as follows:

A L = F F if the first parameter contained aninvalid drive specifier (otherwise AL=OO)

AH = FF if the second parameter containedan invalid drive specifier (otherwise AH=OO)

For EXE programs:

• DS and ES registers are set to point to theProgram Segment Prefix.

• CS, IP, SS, and SP registers are set to the valuespassed by the linker.

For COM programs:

• All four segment registers contain the segmentaddress of the initial allocation block, that startswith the Program Segment Prefix control block.

• All of user memory is allocated to the program. I f

the program wishes to invoke another programthrough the EX EC function call, it must first freesome memory through the Setblock (hex 4A)function call to provide space for the program

being invoked.

• The Instruction Pointer (IP) is set to hex 100.

• SP register is set to the end of the program ssegment. The segment size at offset 6 is reducedby hex 100 to allow for a stack of that size.

• A word of zeros is placed on the top of the stack.

The Program Segment Prefix (with offsets inhexadecimal) is formatted s follows.



Program Segment Prefix

offsets in hex)0

Top of Long call toINT hex 20 Reserved DOS function dis-emory

patcher 5 bytes)28 CTRL-BREAKTerminate addresslP,CS) exit address

lP)10 ICTRL-BREAK CRITICALERROR

exit address exit addressCS) lP, CS)

~IUsed by DOS

2CNote 3

Formatted Parameter Area 1formatted as standard unopened FCB

6C IFormatted Parameter Area 2formatted as standard unopened FCBoverlaid if FCB at hex 5C is opened)

8 ~ ~

Unformatted parameter area

= ' , Tdefault disk transfer area)

1 ~

6-9



6 10

I . First segment of available memory is in segmentparagraph) form for example, hex 1000 would

represent 64K).

2. The word at offset 6 contains the number of bytesavailable in the segment.

3 Offset hex 2C contains the segment address of theenvironment.

4. Programs must not alter any part of the S belowoffset hex 5 C.



C '

7 TI hex FF I Zeros

- - - FCB

Attribute I extension~ i - - - - - - - ~ - - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ~ - -

Drive Filename (8 bytes) or Reserved device name

8 r l - - - - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - - r - - - - - - - - - - - - - - - ~ - - - - - - - -

16

4

3

Currentrecord

Filename extension Current block

Random recordnumber (low part)

Random recordnumber (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

StandardFCB

S ) ~ O U IIOlluO:)

n

jo::sf 't- 'tot:Co( )



Standard File Control Block

6-12

The standard file control block FCB) s defined asfollows, with the offsets in decimal:

Byte Function

o Drive number. For example,

1-8

9-11

12-13

Before open: 0 - default driveI - drive A

After open:

2 - drive Betc.

I - drive A2 - drive Betc.

A 0 s replaced by the actual drive numberduring open.

Filename, left-justified with trailing blanks. Ifa reserved device name s placed here suchas LPTI), do not include the optional colon.

Filename extension, left-justified with trailingblanks can be all blanks).

Current block number relative to thebeginning of the file, starting with zero set tozero by the open function call). A blockconsists of 128 records, each of the sizespecified n the logical record size field. Thecurrent block number s used with the currentrecord field below) for sequential reads andwrites.



14-15

16-19

20-21

Logical record size in bytes. Set to hex 80 bythe open function call. If this is not correct,you must set the value because OS uses itto determine the proper locations in the file

for all disk reads and writes.

File size in bytes. In this 2-word field, thefirst word is the low-order part of the size.

ate the file was created or last updated. Themm dd yy are mapped in the bits as follows:

2 > 20 >

5 14 3 12 10 9 8 7 6 5 4 3 2 1 0y m m m m

22-31

32

33-36

where:

mm is 1-12dd is 1-31yy is 0-119 1980-2099)

Reserved for system use.

Current relative record number 0-127)within the current block. See above.) Youmust set this field before doing sequentialread/write operations to the diskette. This

field is not initialized by the open functioncall. )

Relative record number relative to thebeginning of the file, starting with zero. Youmust set this field before doing random read/write operations to the diskette. This field is

not initialized by the open function call.)

6-13



6 14

f the record size is less than 64 bytes, bothwords are used. Otherwise, only the firstthree bytes are used. Note that if you use theFile Control Block at hex 5 C in the programsegment, the last byte of the FCB overlaps

the first byteof

the unformatted parameterarea.

Notes:

1 An unopened FCB consists of the FCB

prefix if used), drive number, andfilename/extensions properly filled in.An open FCB is one in which theremaining fields have been filled in bythe Create or Open function calls.

2. Bytes 0-15 and 32-36 must be set by theuser program. Bytes 16-31 are set byDOS and must not be changed by userprograms.

3. All word fields are stored with the leastsignificant byte first. For example, arecord length of 128 is stored as hex 80at offset 14, and hex at offset 15.



Extended File Control lock

The extended File Control Block s used to create orsearch for files in the disk directory that have specialattributes.

t adds a 7-byte prefix to the FCB, formatted asfollows:

Byte Function

FCB-7 Flag byte containing hex F F toindicate an extended FCB.

FCB-6 to FCB-2 Reserved.

FCB-I Attribute byte. See DOS DiskDirectory n Chapter 4 of thismanual for attribute bit definitions.Also refer to function call hex

( search first) for details on usingthe attribute bits during directorysearches. This function s presentto allow applications to define theirown files as hi en (and therebyexclude them from directorysearches), and to allow selectivedirectory searches.

Any references in the DOS Function Calls (refer toChapter 5 of this manual) to an FCB, whether openedor unopened, may use either a normal or extendedFCB. I f using an extended FCB, the appropriateregister should be set to the first byte of the prefix,rather than the drive-number field.

6-15



6 16



Chapter 7 Executing Commandsfrom Within anApplication

7 1



7 2



With DOS Version 2.10, application programs mayinvoke a secondary copy of the command processor.Your program may pass a DOS command as aparameter and the secondary command processor willexecute as though it had been entered from the standard

input device. The procedure is:

1 Assure that adequate free memory 17K) exists tocontain the second copy of the command processorand the command it is to execute.

2 Build a parameter string for the secondarycommand processor in the form:

1 byte = length of parameter stringbyte = parameter string

1 byte = hex OD carriage return)

For example, the assembly statement below wouldbuild the string to cause execution of aDISKCOPY command:

DB 14, DlSKCOPY A B: ,13

3 Use the EXEC function call hex 4B, functionvalue 0) to cause execution of the secondary copyof the command processor the drive, directory andname of the command processor can be obtained

from the COMSPEC=parameter in theenvironment passed to you at PSP hex 2C).Remember to set offset 2 of the EXEC controlblock to point to the parameter string built above.

7-3



7 4



The IBM Personal Computer Fixed Disk SupportArchitecture has been designed to meet the followingobjectives:

• Allow multiple operating systems to utilize thefixed disk without the need to dump/restore whenchanging operating systems.

• Allow a user-selected operating system to bestarted from the fixed disk.

Fixed isk rchitecture

The architecture s defined as follows:

• In order to sh re the fixed disk among operatingsystems, the disk may be logically divided into 1 to4 partitions. The space within a given partitions contiguous, and can be dedicated to a specific

operating system. Each operating system may

own only one partition. The number and sizes ofthe partitions are user-selectable through a fixeddisk utility program. (The DOS utility s

FDISK.COM.) The partition information s keptin a partition table that is imbedded in the masterfixed disk boot record on the first sector of thedisk.

• Any operating system must consider its partition tobe an entire disk, and must ensure that itsfunctions and utilities do not access otherpartitions on the disk.

8 3



• Each partition can contain a boot record on its firstsector, and any other programs or data that youchoose-including a copy of an operating system.For example, the DOS FORM T command maybe used to format (and place a copy of DOS in)the DOS partition in the same manner that adiskette is formatted. With the FDISK utility, youmay designate a partition as bootable (active)the master fixed disk boot record will cause thatpartition's boot record to receive control when thesystem is started or restarted.

System nitialization

8 4

The System initialization (or system boot) sequence isas follows:

1 System initialization first attempts to load anoperating system from diskette drive A. If the driveis not ready or a read error occurs, it then attempts

to read a master fixed disk boot record from thefirst sector of the first fixed disk on the system. I f

unsuccessful, or if no fixed disk is present, itinvokes ROM BASIC.

2. If successful, the master fixed disk boot record is

given control and it examines the partition tableimbedded within it. If one of the entries indicates abootable (active) partition, its boot record is

read (from the partition's first sector) and givencontrol.

3. I f none of the partitions is bootable, ROM BASICis invoked.



4 f any of the boot indicators are invalid, or if morethan one indicator is marked as bootable, themessage Invalid partition table is displayed andthe system enters an enabled loop. You may theninsert a system diskette in drive A and use systemreset to restart from diskette.

5. f the partition's boot record can t be successfullyread within 5 retries due to read errors, themessage Error loading operat ing system appearsand the system enters an enabled loop.

6 If the partition's boot record does not contain a

valid signature (see Boot Record/PartitionTable ), the message Missing operating systemappears, and the system enters an enabled loop.

Note: When changing the size or location of anypartition, you must ensure that all existing data onthe disk has been backed up (the partitioningprocess will lose track of the previous partition

boundaries) .

8 5



Boot Record Partition Table

8 6

A fixed disk boot record must be written on the firstsector of all fixed disks, and contain:

1Code to load (and give control to) the boot recordfor 1 of 4 possible operating systems.

2 A partition table at the end of the boot record.Each table entry is 16 bytes long, and contains thestarting and ending cylinder, sector and head foreach of 4 possible partitions, as well as the numberof sectors preceding the partition and the number

of sectors occupied by the partition. The bootindicator byte is used by the boot record todetermine if one of the partitions contains aloadable operating system. F ISK initializationutilities mark a user-selected partition as

bootable by placing a value of hex 80 in thecorresponding partition's boot indicator (setting allother partitions' indicators to zero at the sametime.) The presence of the hex 80 tells thestandard boot routine to load the sector whoselocation is contained in the following 3 bytes. Thatsector will be the actual boot record for theselected operating system, and t will beresponsible for the remainder of the system'sloading process (as it is from diskette). All bootrecords are loaded at absolute address 0:7COO



The partition table (with its offsets into the bootrecord) is s follows:

Of s Purpose Head Sector ylinder

1 BE Partition 1 begin boot ind H S CYL

1 C2 Partition 1 end syst ind H S CYL

1 C6 Partition 1 rei sect Low word High word

1 CA Partition 1 sects Low word High word

1 CE Partition 2 begin boot ind H S CYL

1 02 Partition 2 end syst ind H S CYL

1 06 Partition 2 rei sect Low word High word

1 O Partition 2 sects Low word High word

1 DE Partition 3 begin boot ind H S CYL

1 E2 Partition 3 end syst ind H S CYL

1 E6 Partition 3 rei sect Low word High word

1 EA Partition 3 sects Low word High word

1 EE Partition 4 begin boot ind H S CYL

1 F2 Partition 4 end syst ind H S CYL

1 F6 Partition 4 rei sect Low word High word

1 FA Partition 4 sects Low word High word

1 FE Signature hex 55 hex AA

8 7



Technical nformation

8 8

When shipped by IBM, the 10-megabyte fixed disks areformatted with 512-byte sectors at an interleave factorof 6 (17 sectors per track, 4 heads per cylinder). Theycontain no data or boot records.

The boot indicator byte must contain 0 for anon-bootable partition, or hex 80 for a bootablepartition. Only one partition can be marked bootable.

The syst ind field contains an indicator of theoperating system that owns the partition. Each

operating system can own only one partition.

The system indicators are:

hex 00 - unknown (unspecified)hex 01 - DOS

The I-byte fields labelled CYL contain the low-order8 bits of the cylinder number-the high order 2 bits arein the high order 2 bits of the S (sector) field. Thiscorresponds with ROM BIOS Interrupt hex 13 (diskI/O) requirements, to allow for a 10-bit cylindernumber.

The fields are ordered in such a manner that only2 MOV instructions are required to properly set up theDX and CX registers for a ROM BIOS call to load theappropriate boot record (fixed disk booting is onlypossible from the first fixed disk on a system, whoseBIOS drive number (hex 80) corresponds to the bootindicator byte.)

All partitions are allocated in cylinder multiples and

begin on sector 1 head O EXCEPTION: the partitionwhich is allocated at the beginning of the disk starts atsector 2, to account for the disk's master boot record.



The number of sectors preceding each partition on thedisk is kept in the 4-byte field labelled reI sect. Thisvalue is obtained by counting the sectors beginning withcy Under 0, sector 1 head ° f the disk, andincrementing the sector, head and then track values upto the beginning of the partition. Thus, if the disk has17 sectors per track and 4 heads, and the secondpartition begins at cylinder 1 sector 1 head 0, thepartition's starting relative sector is 68 (decimal)-therewere 1 7 sectors on each of 4 heads on 1 track allocatedahead of it. The field is stored with the least significantword first.

The numberof

sectors allocated to the partition is keptin the # of sects field. This is a 4-byte field storedleast significant word first.

The last 2 bytes of the boot record (hex 55AA) areused as a signature to identify a valid boot record. Boththis record and the p r t i t ~ o nboot records are required tocontain the s i g n t ~ r eat offset hex IFE.

The Master disk boot record will invoke ROM BASICif no indicator byte reflects a bootable system.

When a partition's boot record is given control, it ispassed its partition table entry address in the DS: SIregisters.

8 9



8 10

System programmers designing a utility toinitialize/manage a fixed disk must provide thefollowing functions at a minimum:

1 Write the master disk boot record/partition tableto the disk s first sector to initialize it.

2. Perform partitioning o the disk-that is, create or

update partition table information (all fields for thepartition) when the user wishes to create apartition. This may be limited to creating apartition for only one type o operating system, butmust allow repartitioning the entire disk, or adding

a partition without interfering with existingpartitions (user s choice).

3. Provide a means for marking a user-specifiedpartition as bootable, and resetting the bootableindicator bytes for all other partitions at the sametime.



Chapter 9 X File Structureand Loading

9 1



9 2



The .EXE files produced by the Linker program consistof two parts:

• Control and relocation information

• The load module itself

The control and relocation information, which is

described below, is at the beginning of the file in an areaknown as the header. The load module immediatelyfollows the header. The load module is the memoryimage of the module constructed by the linker.

The header is formatted as follows:

Hex Offset Contents

00-01 Hex 4D hex A This is the LINK program ssignature to mark the file as a valid .EXE file.

02-03 Length of image mod 512 (remainder afterdividing the load module image size by 512).

04-05 Size of the file in 512-byte increments pages),including the header.

06-07 Number of relocation table items that follow theformatted portion of the header.

08-09 Size of the header in 16-byte incrementsparagraphs). This is used to locate the

beginning of the load module in the file.

OA OB Minimum number of 16-byte paragraphsrequired above the end of the loaded program.

9-3



Hex Offset Contents

oc on Maximum number of 16-byte paragraphsrequired above the end of the loadedprogram.

OE OF Offset of stack segment in load module insegment form).

10-11 Value to be in the SP register when themodule is given control.

12-13 Word checksum - negative sum of all thewords in the file, ignoring overflow.

14-15 Value to be in the IP register when themodule is given control.

16-17 Offset of code segment within load modulein segment form).

18-19 Offset of the first relocation item within thefile.

lA-IB Overlay number 0 for resident part of theprogram).

9 4



The relocation table follows the formatted area justdescribed. The relocation table is made up of a variablenumber of relocation items. The number of items is

contained at offset 06-07. The relocation item containstwo f ie lds a 2-byte offset value, followed by a 2-byte

segment value. These two fields contain the offset intothe load module of a word which requires modificationbefore the module is given control. This process is

called relocation and is accomplished as follows:

1 A Program Segment Prefix is built following theresident portion of the program that is performingthe load operation.

2. The formatted part of the header is read intomemory (it s size is at offset 08-09).

3. The load module size is determined by subtractingthe header size from the file size. Offsets 04-05and 08-09 can be used for this calculation. The

actual size is downward adjusted based on thecontents of offsets 02-03. Note that all filescreated by pre-release 1.10 LINK programsalways placed a value of 4 at that location,regardless of actual program size. Therefore, we

recommend that this field be ignored if it containsa value of 4. Based on the setting of the high/lowloader switch, an appropriate segment is

determined at which to load the load module. Thissegment is called the start segment

4 The load module is read into memory beginning atthe start segment.

5. The relocation table items are read into a workarea (one or more at a time).

9-5



9·6

6 Each relocation table item segment value is addedto the start segment value. This calculatedsegment in conjunction with the relocation itemoffset value points to a word in the load module towhich is added the start segment value. The resultis placed back into the word in the load module.

7 Olice all relocation items have been processed theSS and SP registers are set from the values in theheader and the start segment value is added to SS.The ES and S registers are set to the segmentaddress of the Program Segment Prefix. The startsegment value is added to the header C S register

value. The result along with the headerIP

valueis used to give the module control.



Chapter 10 OS MemoryManagement

Effective with DOS 2.00, DOS now keeps track of

allocated and available memory blocks, and provides 3function calls for application programs to communicatetheir memory needs to DOS. These calls are x 48 toallocate a memory block, x 49 to free a previouslyallocated memory block, and x 4A (SETBLOCK) tochange the size of an allocated memory block.

Memory is managed as follows:

Beginning with 2.00, DOS builds a control block foreach block of memory, whether free or allocated. For

example, if a program issues an allocate call,DOS

locates a block of free memory that satisfies the request,and will carve the requested memory out of that block.The requesting program is passed the location of thefirst byte of the block that was allocated for it - amemory management control block, describing theallocatd block, has been built or the allocated block(and a second memory management control block

describes the amount of space left in the original freeblock of memory). When a SETBLOCK is done toshrink an allocated block, DO S builds a memorymanagement control block for the area being freed, andadds it to the chain of control blocks. Thus, anyprogram that changes memory that is not allocated to it,stands a good chance of destroying a DOS memorymanagement control block. This causes unpredictableresults that don t show up until an activity is performedwhere DOS uses its chain of control blocks (the normalresult is a memory allocation error, for which the onlycure is to restart the system).

10 1



10-2

When a program (command, application program) s tobe loaded, DOS uses the EXEC function call (x 48 ) toperform the loading. This is the same function call thats available to application programs for loading other

programs. This function call has 2 options in release2.00 and 2.10 - function 0, to load and execute aprogram (this s what the command processor uses toload and execute external commands), and function 3,to load an overlay (program) without executing it.Although both functions perform their loading in thesame way (relocation s performed for .EXE files), theirhandling of memory management s different.

F or function 0 to load and execute a program, EXECfirst allocates the largest available block of memory (thenew program s PSP will be at offset 0 in that memoryblock). Then EXEC loads the program. Thus, in mostcases, the new program owns all of the memory fromits PSP to the highest end of memory, including thememory occupied by the transient part ofCOMMAND. COM which contains the loader. If the

program were to issue its own EXEC function call toload and execute another program, the request wouldfail because no available memory exists to load the newprogram into. To further complicate things, if the callingprogram has overlaid the loader in COMMAND.COM

available memory has to be found to load the loaderinto, before the loader can load the required program.

Note: for .EXE programs, the amount of memoryallocated is the size of the program s memoryimage plus the value in the MAX ALLOC field of

the file s header (offset x OC ), if that muchmemory is available. If not, EXEC will allocatethe size of the program s memory image plus thevalue in the MIN ALLOC field in the header

(offset x OA ). These fields are set by the LINKer.For release 2.00 and 2.10, they are set to defaultvalues that cause the largest available memoryblock to be allocated.



10 4

Programs loaded via function 3 should not issue anySE T LOCK calls, since they don t own the memorythey are operating in (the memory s own by the c llingprogram).

Because programs loaded via function 3 are givencontrol directly by (and return control directly to) thecalling program with no DOS intervention, no memorys automatically freed when the called program exits - its up to the calling program to determine the disposition

of the memory that had been occupied by the exitingprogram. Note that if the exiting program had itselfallocated any memory, it is responsible for freeing thatmemory before exiting.



ndex

Special Characters

application executingcommands within your 7-3

/S option 4-7

Aabsolute disk read 5-10absolute disk write 5-11access random 1-6address terminate

interrupt 5-4AH register 5-11

allocating disk space 1-6allocating space 1-6

allocating diskettespace 4-8

allocation tableinformation 5-25

allocation diskette 4-3allocation 4-3 4-4disk allocation 4-3

architecture 8088 1-3structure 3

ASCII codes extended 5-17ASCIIZ string 5-15Asynchronous

Communications

Adapter 5-18attribute byte 6-15attribute field 3-6attribute file 4-5AUTOEXEC file 1-5

Auxiliary AsynchronousCommunicationsAdapter 5-18

auxiliary input 5-18auxiliary output 5-18available functions DOS 1-6A X register 5-6 5-16

Bbatch file processor 1-5BIOS 5 10

BIOS interface module 1-3BIOS Parameter Block 3-15

block devices 3-5block number current 6-12block read random 5-26 5-28block write random 5-26

5-28size 5-25

blocking/deblocking data 1-3BP register 5-6BPB what is 3-16buffered standard input 5-19buffers file 5-3built-in functions 1-3BX register 5-6byte attribute 6-15byte flag 6-15

X I



ccalls, function 5-13chaining file sectors 1-6character devices 3-5

check keyboard status 5-20checksum methodology 1 5

CL register 5-16close file 5-21cluster number, relative 4-7cluster, calculate 4-10cluster, locate next 4-9, 4-10cluster, starting 4-7

clusters 1-6, 4-3directory 4-5diskette directory 4-4

codes, error 5-6COM filename extension 1 5

.COM 1 5

.EXE 1-5COM programs 6-8command processor 1-4command processor, resident

portion of 1-4COMMAND.COM 1-4,4-7,

6-3Communications Adapter,

Auxiliary Asynchronous5-18

console I/O, direct 5-19control blocks 6-15control screen cursor 2-3create file 5-24creating a device driver 3-8critical error handler

vector 5-5

CS register 5-3, 5-7, 6-8CTRL-BREAK exit

address 1-5,5-4CTRL-BREAK handler 1-5current block number 6-12

X-2

current disk 5 -25current relative record

number 6-13cursor control 2-3CX register 5-6

data blocking/deblocking 1-3date file created or

updated 6-12deblocking/blocking, data 1-3

Initialization 1-4delete file 5-23device driver, creating 3-9device drivers 3-3device drivers,

installation 3-10device field, next 3-6device header 3-6devices, types of 3-4DI register 5-6direct console I/O 5-19disk

current 5-25reset 5-20select 5-20

disk error handling 1-5disk errors 5-7disk read, absolute 5-10disk transfer address 6-7disk transfer address, set 5-25Disk Transfer Area DIA) 1-7disk write, absolute 5-11display output 5-18

DOS environment 6-6DS register 5-6, 6-8DT A Disk Transfer

Area) 1-7DX register 5-6



end-of-file mark 4-9entries, search for 5-22environment, DOS 6-6

error codes 5-6error handling

critical 1 5

disk 1 5

error return table 5-14error trapping 1-8ES register 5-6, 6-8EXE file structure 9-2EXE filename extension 1-5,

6-3high 1-5

EXE files, load 9-2EXE programs 6-8executing commands within an

application 7-2extended ASCII codes 5-17extended file control

block 6-15external commands 1-6

F

FA T see File AllocationTable)

allocating space 4-8FCB 6-12FCB see File Control Block)field name 3-8field, attribute 3-7File Allocation Table

FAT) 1-4,1-6,4-8file allocation table, how to use

4-10

file buffers 5-3File Control Block FCB) 1-7,

6-11extended 6-15standard 6-11

File Management 1-6file sectors

chaining 1-6mapping 1-6

file size 6-13file structure, .EXE 9-3filename, parse 5-28Fixed Disk Information 8 1

flag byte 6-15FORMAT command 4-4

hidden 4-4format, device drivers 3-4function call parameters 3-16function calls 5-13functions, available DOS 1-5functions, built-in 1-3

getdate 5-30time 5-30

header 9-3

G

H

hidden files 4-5, 5-24, 6-13attribute 4-6

high memory 1-5

available functions 1-6high/low loader switch 9-5

X-3



IBMBIO.COM 1-3 1-4 4-7IBMDOS.COM 1-3 4-7

initialization DOS 1-3input auxiliary 5-18installation of device

drivers 3-10instruction set 8088 1-2INT hex 24 1-8INT 2 1-6

random 1-6sectors 1-6sequential 1-6

interface module BIOS 1-3internal command

processors 1-5interrupt hex 20 5-3interrupt hex 22 1-5 5-4interrupt hex 23 1-5 5-4interrupt hex 24 5-5interrupt hex 25 5-10interrupt hex 26 5-11interrupt hex 27 5-11interrupt mechanism

8088 1-2interrupt routines 3-8

interrupt vectors 1-4interrupt set 5-27interrupts 5-3IP register 5-7 6-8IRET 5-5

X-4

K

keyboard input 5-17buffered 5-19

keyboard status check 5-20

keys reassigning 2-3

L

linefeed 5-5loading .EXE files 9-2locate next cluster 4-9 4-10

logical record size 6-12logical sector numbers 5-10

M

mapping file sectors 1-6memory management 10-1memory map 6-3MOV instruction 4-10

Nname field 3-8

next device field 3-6

oopen file 5-21output auxiliary 5-18output display 5-18



p

parameters, function call 3-16parse filename 5-28pointer to next device 3-9

print string 5-19printer output 5-18program segment

create new 5-27OS 6-5

Program Segment Prefix 1-4,1-7, 6-8, 6-9

program terminate 5 1 7

random access 1-6random block read 1-6, 5-28random block write 1-6, 5-28

random read 5-26random record field, set 5-24random write 5-26Read-Only Memory

ROM) 1-3read, random 5-26read, random block 5-28read, sequential 5-24

reassign keys 2-2record number, relative 6-13record size, logical 6-11relative record number 6-13relocation 9-5rename file 5-25reset, disk 5-20reset, system 1-4resident portion of command

processor 1 5

ROM Read-OnlyMemory) 1-3

ROM BIOS routine 5-20

routinesmemory management 1-6ROM BIOS 5-19

routines, strategy/interrupt 3-8

sscreen cursor control 2-3search for entries 5-22sector numbers, logical 5-10sectors, file 1-6segment address 6-6

segment, create newprogram 5-27

segment, start 9-5select disk 5-20separators, filename 5-28sequential read 5-24sequential write 5-24set

date 5-30interrupt 5-27random record field 5-27time 5-30verify switch 5-30

set disk transfer address 5-25SI register 5-6single-drive system 5-20size, file 6-13SP register 6-8space allocation 1-6, 4-3SS register 6-8stack, user 5-6start segment 9-5starting cluster 4-7

strategy routines 3-8structure, OS 1-3switch, high/low loader 9-5System Initialization 8-4system prompt 1 5

x s



technical informationDOS 1-3

terminate address

interrupt 5-4terminate program 5 1 7terminate program

interrupt 5-4terminators filename 5-28transfer address disk 6-7transient portion of command

processor 1-5

uuser stack 5-6

vverify switch 5-30

wwork areas 6-3

wrap around 3-23write random 5-25write random block 5-28write sequential 5-24

X 6



Reader s Comment Form

DOS Technical Reference

The Personal ComputerlIardvvare Library

1502346

Your comments assist us in improving the usefulness of

our publication; they are an important part of the inputused for revisions.

IBM may use and distribute any of the information yousupply in any vv y it believes appropriate vvithoutincurring any obligation vvhatever. You may of course

continue to use the information you supply.

Please do not use this form for technical questionsregarding the IBM Personal Computer or programs forthe IBM Personal Computer or for requests foradditional publications; this only delays the response.Instead direct your inquiries or request to yourauthorized IBM Personal Computer dealer.

Comments:



1

BUSINESS R PLY M ILFIRST CLASS PERMIT NO. 321 BOCA RATON, FLORIDA 33432

POSTAGE WILL BE PAID BY ADDRESSEE

IBM PERSONAL COMPUTERSALES SERVICEP.O. BOX 1328 C

BOCA RATON, FLORIDA 33432

9J9 Pia.:

9 delS l U op 9Se9 d

ND PDST GENECESS RYI M ILED

IN THEUNITED ST TES

9d e l



= = = ~- = =-

= ~ = " ' =



The Personal Computerl I a r d ~ a r eLibrary

1502346



IBM may use and distribute any of the information yousupply in any ~ y it believes appropriate ~ i t h o u t

incurring any obligation ~ h a t e v e rYou may of course

continue to use the information you supply.Please do not use this form for technical questionsregarding the IBM Personal Computer or programs forthe IBM Personal Computer or for requests foradditional publications; this only delays the response.Instead direct your inquiries or request to yourauthorized IBM Personal Computer dealer.

Comments:



1

BUSINESS R PLY M ILFIRST CLASS PERMIT NO. 321 BOCA RATON FLORIDA 33432


IBM PERSONAL COMPUTERSALES SERVICEP.O. BOX 1328-CBOCA RATON FLORIDA 33432

aJa4 PIO.::

aldelS lOU op aseald

NO POST GENECESS RYI M ILED

IN THEUNITED ST TES

ade





The Personal ComputerHardware Library

1502346

Your comments assist u in improving the usefulness of


I M may use and distribute any of the information yousupply in any way it believes appropriate withoutincurring any obligation whatever. You may of course

continue to use the information you supply.Please do not use this form for technical questionsregarding the I M Personal Computer or programs forthe I M Personal Computer or for requests for·

additional publications; this only delays the response.Instead direct your inquiries or request to yourauthorized I M Personal Computer dealer.

Comments:



- - : :. =



The Personal ComputerlIardvvare Library

1502346



IBM may use and distribute any of the information yousupply in any vv y it believes appropriate vvithoutincurring any obligation vvhatever. You may of coursecontinue to use the information you supply.

Please do not use this form for technical questionsregarding the IBM Personal Computer or programs forthe IBM Personal Computer or for requests foradditional publications; this only delays the response.Instead direct your inquiries or request to yourauthorized IBM Personal Computer dealer.

Comments:





IBM PERSONAL COMPUTERSALES SERVICEP.O. BOX 1328 CBOCA RATON, FLORIDA 33432

9J94 Pia.:

91delS lOU op aseald

NO POST GENECESS RYIF M ILED

IN THEUNITED ST TES

ade l





IBM PERSONAL COMPUTERSALES & SERVICEP.O. BOX 1328 C

BOCA RATON, FLORIDA 33432

aJa4 Pia:

aldelS l U op aseald

NO POST GENECESS RYI M ILED

IN THEUNITED ST TES

ad e l

1502346 dos 2.10 technical reference sep83

Documents