mirror of https://github.com/AR1972/DOS3.3
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
3175 lines
72 KiB
3175 lines
72 KiB
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
|
|
1.1 Introduction
|
|
|
|
The routines that MS-DOS uses to manage system operation and resources
|
|
can be called by any application program. Using these system calls makes
|
|
it easier to write machine-independent programs and increases the likeli-
|
|
hood that a program will be compatible with future versions of MS-DOS.
|
|
MS-DOS system calls fall into several categories:
|
|
|
|
o Standard character device I/O
|
|
|
|
o Memory management
|
|
|
|
o Process management
|
|
|
|
o File and directory management
|
|
|
|
o Microsoft Network calls
|
|
|
|
o National Language Support calls
|
|
|
|
o Miscellaneous system functions
|
|
|
|
Applications invoke MS-DOS services by using software interrupts. The
|
|
current range of interrupts used for MS-DOS is 20H-27H; 28H-40H are
|
|
reserved. Interrupt 21H is the function request service; it provides access
|
|
to a wide variety of MS-DOS services. In some cases, the full AX register
|
|
is used to specify the requested function. Each interrupt or function
|
|
request uses values in various registers to receive or return function-
|
|
specific information.
|
|
|
|
1.1.1 System Calls That Have Been Superseded
|
|
|
|
Many system calls introduced in versions of MS-DOS earlier than 2.0 have
|
|
been superseded by function requests that are more efficient and easier to
|
|
use. Although MS-DOS still includes these old system calls, they should
|
|
not be used unless it is imperative that a program maintain backward-
|
|
compatibility with versions of MS-DOS before 2.0.
|
|
|
|
A table of the pre-2.0 system calls and a description of the File Control
|
|
Block (required by some of the old calls) appears in Section 1.8, "Old Sys-
|
|
tem Calls."
|
|
|
|
The first part of this chapter explains how DOS manages its resources\(em
|
|
such as memory, files, and processes\(emand briefly describes the purpose of
|
|
most of the system calls. The remainder of the chapter describes each
|
|
interrupt and function request in detail.
|
|
|
|
The system-call descriptions are in numeric order, interrupts followed by
|
|
function requests. These descriptions include further detail on how
|
|
MS-DOS manages its resources.
|
|
|
|
|
|
3
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
Chapter 2 of this manual describes how to write an MS-DOS device driver.
|
|
Chapters 3, 4, and 5 contain more detailed information about MS-DOS,
|
|
including how it manages disk space, the control blocks it uses, and how it
|
|
loads and executes relocatable programs (files with an extension of .exe).
|
|
Chapter 6 describes the Intel object module format. Chapter 7 gives some
|
|
programming hints.
|
|
|
|
1.2 Standard Character Device I/O
|
|
|
|
The standard character function requests handle all input and output to
|
|
and from character devices such as consoles, printers, and serial ports. If a
|
|
program uses these function requests, its input and output can be
|
|
redirected.
|
|
|
|
Table 1.1 lists the MS-DOS function requests for managing standard char-
|
|
acter input and output.
|
|
|
|
Table 1.1
|
|
|
|
Standard Character I/O Function Requests
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
01H
|
|
|
|
Read Keyboard and
|
|
Echo
|
|
|
|
Gets a character from standard input and echoes
|
|
it to standard output
|
|
|
|
02H Display Character Sends a character to standard output
|
|
|
|
03H Auxiliary Input
|
|
|
|
Gets a character from standard auxiliary
|
|
|
|
04H Auxiliary Output
|
|
|
|
Sends a character to standard auxiliary
|
|
|
|
05H Print Character
|
|
|
|
Sends a character to the standard printer
|
|
|
|
06H Direct Console I/O
|
|
|
|
Gets a character from standard input or sends a
|
|
character to standard output
|
|
|
|
07H
|
|
|
|
Direct Console Input
|
|
|
|
Gets a character from standard input
|
|
|
|
08H Read Keyboard
|
|
|
|
Gets a character from standard input
|
|
|
|
09H Display String Sends a string to standard output
|
|
|
|
0AH Gets a string from standard input
|
|
|
|
Buffered Keyboard
|
|
Input
|
|
|
|
0BH
|
|
|
|
Check Keyboard
|
|
Status
|
|
|
|
Reports on the status of the standard input
|
|
buffer
|
|
|
|
0CH
|
|
|
|
Flush Buffer, Read
|
|
Keyboard
|
|
|
|
Empties the standard input buffer and calls one
|
|
of the other standard character I/O function
|
|
requests
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Although several of these standard character I/O function requests seem
|
|
to do the same thing, they are distinguished by whether they check for
|
|
control characters or echo characters from standard input to standard
|
|
|
|
4
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
output. The detailed descriptions later in this chapter point out the
|
|
differences.
|
|
|
|
1.3 Memory Management
|
|
|
|
MS-DOS keeps track of which areas of memory are allocated by writing a
|
|
memory control block at the beginning of each. This control block specifies
|
|
the size of the memory area; the name of the process, if any, that owns the
|
|
memory area; and a pointer to the next area of memory. If the memory
|
|
area is not owned, it is available.
|
|
|
|
Table 1.2 lists the MS-DOS function requests for managing memory.
|
|
|
|
Table 1.2
|
|
|
|
Memory Management Function Requests
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
48H Allocate Memory Requests a block of memory
|
|
|
|
49H
|
|
|
|
Free Allocated
|
|
Memory
|
|
|
|
Frees a block of memory previously allocated with 48H
|
|
|
|
|
|
4AH Set Block
|
|
|
|
Changes the size of an allocated memory block
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
When a process requests additional memory with Function 48H (Allocate
|
|
Memory), MS-DOS searches for a block of available memory large enough
|
|
to satisfy the request. If it finds such a block of memory, it changes the
|
|
memory control block to show the owning process. If the block of memory
|
|
is larger than the requested amount, MS-DOS changes the size field of the
|
|
memory control block to the requested amount, writes a new memory con-
|
|
trol block at the beginning of the unneeded portion showing that it is
|
|
available, and updates the pointers to add this memory to the chain of
|
|
memory control blocks. MS-DOS then returns the segment address of the
|
|
first byte of the allocated memory to the requesting process.
|
|
|
|
When a process releases an allocated block of memory with Function 49H
|
|
(Free Allocated Memory), MS-DOS changes the memory control block to
|
|
show that it is available (not owned by any process).
|
|
|
|
When a process uses Function 4AH (Set Block) to shrink an allocated
|
|
block of memory, MS-DOS builds a memory control block for the memory
|
|
being released and adds it to the chain of memory control blocks. When a
|
|
process tries to use Function 4AH (Set Block) to expand an allocated block
|
|
of memory, MS-DOS treats it as a request for additional memory rather
|
|
than returning the segment address of the additional memory to the
|
|
requesting process. However, MS-DOS simply chains the additional
|
|
memory to the existing memory block.
|
|
|
|
5
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
If MS-DOS can't find a block of available memory large enough to satisfy a
|
|
request for additional memory made with either Function 48H (Allocate
|
|
Memory) or Function 4AH (Set Block), MS-DOS returns an error code to
|
|
the requesting process.
|
|
|
|
When a program receives control, it should call Function 4AH (Set Block)
|
|
to shrink its initial memory-allocation block (the block that begins with
|
|
its Program Segment Prefix) to the minimum it requires. This frees
|
|
unneeded memory and makes the best application design for portability to
|
|
future multitasking environments.
|
|
|
|
When a program exits, MS-DOS automatically frees its initial memory-
|
|
allocation block before returning control to the calling program
|
|
(command.com is usually the calling program for application programs).
|
|
The DOS frees any memory owned by the exiting process.
|
|
|
|
Any program that changes memory that is not allocated to it will most
|
|
likely destroy at least one memory-management control block. This
|
|
causes a memory-allocation error the next time MS-DOS tries to use the
|
|
chain of memory control blocks; the only cure is to restart the system.
|
|
|
|
1.4 Process Management
|
|
|
|
MS-DOS uses several function requests to load, execute, and terminate
|
|
programs. Application programs can use these same function requests to
|
|
manage other programs.
|
|
|
|
Table 1.3 lists the MS-DOS function requests for managing processes.
|
|
|
|
Table 1.3
|
|
|
|
Process-Management Function Requests
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
31H Keep Process
|
|
|
|
Terminates a process and returns control to the
|
|
invoking process, but keeps the terminated
|
|
process in memory
|
|
|
|
4BH Loads and executes a program
|
|
|
|
Load and Execute
|
|
Program
|
|
|
|
4B03H Load Overlay
|
|
|
|
Loads a program overlay without executing it
|
|
|
|
4CH End Process
|
|
|
|
Returns control to the invoking process
|
|
|
|
4DH
|
|
|
|
Get Return Code of
|
|
Child Process
|
|
|
|
Returns a code passed by an exiting child process
|
|
|
|
|
|
62H Get PSP
|
|
|
|
Returns the segment address of the current
|
|
process's Program Segment Prefix
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
|
|
6
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
|
|
1.4.1 Loading and Executing a Program
|
|
|
|
When a program uses Function 4BH (Load and Execute Program) to load
|
|
and execute another program, MS-DOS allocates memory, writes a Pro-
|
|
gram Segment Prefix (PSP) for the new program at offset 0 of the allo-
|
|
cated memory, loads the new program, and passes control to it. When the
|
|
invoked program exits, control returns to the calling program.
|
|
|
|
Command.com uses Function 4BH to load and execute command files.
|
|
Application programs have the same degree of control over process
|
|
management as does command.com.
|
|
|
|
In addition to these common features, there are some differences in the
|
|
way MS-DOS loads .com and .exe files.
|
|
|
|
Loading a .Com Program
|
|
|
|
When command.com loads and executes a .com program, it allocates all
|
|
available memory to the application and sets the stack pointer 100H bytes
|
|
from the end of available memory. A .com program should set up its own
|
|
stack before shrinking its initial memory-allocation block with Function
|
|
4AH (Set Block) because the default stack is in the memory to be released.
|
|
|
|
If a newly loaded program is allocated all of memory\(emas a .com program
|
|
is\(emor requests all of available memory by using Function 48H (Allocate
|
|
Memory), MS-DOS allocates to it the memory occupied by the transient
|
|
part of command.com. If the program changes this memory, MS-DOS
|
|
must reload the transient portion of command.com before it can continue.
|
|
If a program exits (via Function 31H, Keep Process) without releasing
|
|
enough memory, the system halts and must be reset. To minimize this pos-
|
|
sibility, a .com program should use Function 4AH (Set Block) to shrink its
|
|
initial allocation block before doing anything else, and before exiting, all
|
|
programs must release all memory they allocate by using Function 48H
|
|
(Allocate Memory).
|
|
|
|
Loading an .Exe Program
|
|
|
|
When command.com loads and executes an .exe program, it allocates the
|
|
size of the program's memory image plus either the value in the
|
|
MAX_ALLOC field (offset 0CH) of the file header (if that much memory is
|
|
available) or the value in the MIN_ALLOC field (offset 0AH). The linker
|
|
sets these fields. Before passing control to the .exe file, MS-DOS uses the
|
|
relocation information in the file header to calculate the correct relocation
|
|
addresses.
|
|
|
|
|
|
|
|
7
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
For a more detailed description of how MS-DOS loads .com and .exe files,
|
|
see Chapter 3, "MS-DOS Technical Information," and Chapter 4, "MS-
|
|
DOS Control Blocks and Work Areas."
|
|
|
|
Executing a Program from Within Another Program
|
|
|
|
Since command.com builds pathnames, searches directory paths for exe-
|
|
cutable files, and relocates .exe files, the simplest way to load and execute
|
|
a program is to load and execute an additional copy of command.com,
|
|
passing it a command line that includes the /C switch, which invokes the
|
|
.com or .exe file. The description of Function 4B00H (Load and Execute
|
|
Program) describes how to do this.
|
|
|
|
1.4.2 Loading an Overlay
|
|
|
|
When a program uses Function 4B03H (Load Overlay) to load an overlay,
|
|
it must pass MS-DOS the segment address at which the overlay is to be
|
|
loaded. The program must call the overlay, which then returns directly to
|
|
the calling program. The calling program is in complete control: MS-DOS
|
|
does not write a PSP for the overlay or intervene in any other way.
|
|
|
|
MS-DOS does not check to see if the calling program owns the memory
|
|
where the overlay is to be loaded. If the calling program does not own the
|
|
memory, loading the overlay will most likely destroy a memory-control
|
|
block, causing an eventual memory-allocation error.
|
|
|
|
Therefore, a program that loads an overlay must either allow room for the
|
|
overlay when it calls Function 4AH (Set Block) to shrink its initial
|
|
memory-allocation block, or shrink its initial memory-allocation block to
|
|
the minimum and then use Function 48H (Allocate Memory) to allocate
|
|
memory for the overlay.
|
|
|
|
1.5 File and Directory Management
|
|
|
|
The MS-DOS hierarchical (multilevel) file system is similar to that of the
|
|
XENIX operating system. For a description of the multilevel directory sys-
|
|
tem and how to use it, see the MS-DOS User's Reference.
|
|
|
|
1.5.1 Handles
|
|
|
|
To create or open a file, a program passes MS-DOS a pathname and the
|
|
attribute to be assigned to the file. MS-DOS returns a 16-bit number,
|
|
called a handle. For most subsequent actions, MS-DOS requires only this
|
|
handle to identify the file.
|
|
|
|
8
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
A handle can refer to either a file or a device. MS-DOS predefines five stan-
|
|
dard handles. These handles are always open, so you needn't open them
|
|
before you use them. Table 1.4 lists these predefined handles.
|
|
|
|
Table 1.4
|
|
|
|
Predefined Device Handles
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Handle Standard device Comment
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
0 Input Can be redirected from command line
|
|
1 Output Can be redirected from command line
|
|
2 Error
|
|
3 Auxiliary
|
|
4 Printer
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
When MS-DOS creates or opens a file, it assigns the first available handle.
|
|
Since a program can have 20 open handles, including the five predefined
|
|
handles, it typically can open 15 extra files. By using Function 46H (Force
|
|
Duplicate File Handle), MS-DOS can temporarily force any of the five
|
|
predefined handles to refer to an alternate file or device. For more infor-
|
|
mation about Function 46H, see its description later in this chapter.
|
|
|
|
1.5.2 File-Related Function Requests
|
|
|
|
MS-DOS treats a file as a string of bytes; it assumes no record structure or
|
|
access technique. An application program imposes whatever record struc-
|
|
ture it needs on this string of bytes. Reading from or writing to a file
|
|
requires only pointing to the data buffer and specifying the number of
|
|
bytes to read or write.
|
|
|
|
Table 1.5 lists the MS-DOS function requests for managing files.
|
|
|
|
Table 1.5
|
|
|
|
File-Related Function Requests
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
3CH Create Handle Creates a file
|
|
|
|
3DH Open Handle Opens a file
|
|
|
|
3EH Close Handle Closes a file
|
|
|
|
3FH Read Handle Reads from a file
|
|
|
|
40H Write Handle Writes to a file
|
|
|
|
42H Move File Pointer Sets the read/write pointer in a file
|
|
|
|
45H Duplicate File Handle
|
|
|
|
Creates a new handle that refers to the same
|
|
file as an existing handle
|
|
|
|
|
|
|
|
9
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
46H Force Duplicate File Handle
|
|
|
|
Makes an existing handle refer to the same file
|
|
as another existing handle
|
|
|
|
5AH Create Temporary File Creates a file with a unique name
|
|
|
|
5BH Create New File
|
|
|
|
Attempts to create a file, but fails if a file with
|
|
the same name exists
|
|
|
|
67H Set Handle Count
|
|
|
|
Increases or decreases the number of files a
|
|
program can have open at one time
|
|
|
|
68H Commit File
|
|
|
|
Flushes buffered data for a file without closing
|
|
it to ensure the disk image of that file is
|
|
current
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
|
|
File Sharing
|
|
|
|
Version 3.1 of MS-DOS introduces file sharing, which lets more than one
|
|
process share access to a file. File sharing operates only after the share
|
|
command has been executed to load file-sharing support. That is, you
|
|
must use the share command to take advantage of file sharing.
|
|
|
|
Table 1.6 lists the MS-DOS function requests for sharing files; if file shar-
|
|
ing is not in effect, these function requests cannot be used. Function 3DH
|
|
(Open Handle) can operate in several modes. Here it is referred to in the
|
|
file-sharing modes, which require file sharing to be in effect. (Compatibil-
|
|
ity mode is usable without file sharing in effect.)
|
|
|
|
Table 1.6
|
|
|
|
File-Sharing Function Requests
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
3DH Open Handle
|
|
|
|
Opens a file by using one of the file-sharing modes
|
|
|
|
440BH IOCtl Retry
|
|
|
|
(before Interrupt 24 is issued) Specifies how many
|
|
times to retry an I/O operation that fails due to a file-
|
|
sharing violation
|
|
|
|
5C00H Lock Locks a region of a file
|
|
|
|
5C01H Unlock Unlocks a region of a file
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
|
|
1.5.3 Device-Related Function Requests
|
|
|
|
I/O Control for devices is implemented with Function 44H (IOCtl), which
|
|
includes several subfunctions necessary to perform device-related tasks.
|
|
Some forms of the IOCtl function request require that the device driver be
|
|
written to support the IOCtl interface. Table 1.7 lists the MS-DOS func-
|
|
tion requests for managing devices.
|
|
|
|
Table 1.7
|
|
|
|
Device-Related Function Requests
|
|
|
|
10
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
4400H,01H IOCtl Data Gets or sets device description
|
|
|
|
4402H,03H IOCtl Character
|
|
|
|
Gets or sets character-device control data
|
|
|
|
4404H,05H IOCtl Block
|
|
|
|
Gets or sets block-device control data
|
|
|
|
4406H,07H IOCtl Status
|
|
|
|
Checks device input or output status
|
|
|
|
4408H IOCtl Is Changeable
|
|
|
|
Checks whether block device contains
|
|
removable medium
|
|
|
|
440CH Generic IOCtl (for handles)
|
|
|
|
Sets Generic IOCtl for handles and
|
|
supports code pages for devices
|
|
|
|
440DH Generic IOCtl (for devices) Sets Generic IOCtl for devices
|
|
|
|
440E,0FH Get/Set IOCtl Drive Map Gets or sets logical drive map
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Some forms of the IOCtl function request can be used only with Microsoft
|
|
Networks; these forms are listed in Section 1.6, "Microsoft Networks."
|
|
|
|
1.5.4 Directory-Related Function Requests
|
|
|
|
A directory entry is a 32-byte record that includes the file's name, exten-
|
|
sion, date and time of last change, and size. An entry in a subdirectory is
|
|
identical to an entry in the root directory. Directory entries are described
|
|
in detail in Chapter 3.
|
|
|
|
The root directory on a disk has room for a fixed number of entries: 64 on
|
|
a standard single-sided disk, 112 on a standard double-sided disk. For
|
|
hard disks, the number of directories depends on the DOS partition size.
|
|
A subdirectory is simply a file with a unique attribute; there can be as
|
|
many subdirectories on a disk as space allows. The depth of a directory
|
|
structure, therefore, is limited only by the amount of storage on a disk and
|
|
the maximum pathname length of 64 characters. Pre-2.0 disks appear to
|
|
have only a root directory that contains files but no subdirectories.
|
|
|
|
Table 1.8 lists the MS-DOS function requests for managing directories.
|
|
|
|
Table 1.8
|
|
|
|
Directory-Related Function Requests
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
39H Create Directory Creates a subdirectory
|
|
|
|
3AH Remove Directory Deletes a subdirectory
|
|
|
|
3BH Change Current Directory Changes the current directory
|
|
|
|
41H Delete Directory Entry (Unlink) Deletes a file
|
|
|
|
43H Get/Set File Attributes (Chmod)
|
|
|
|
Retrieves or changes the attributes of a file
|
|
|
|
47H Get Current Directory
|
|
|
|
Returns current directory for a given drive
|
|
|
|
|
|
|
|
11
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
4EH Find First File
|
|
|
|
Searches a directory for the first entry that
|
|
matches a filename
|
|
|
|
4FH Find Next File
|
|
|
|
Searches a directory for the next entry that
|
|
matches a filename
|
|
|
|
56H Change Directory Entry Renames a file
|
|
|
|
57H Get/Set Date/Time of File
|
|
|
|
Changes the time and date of last change in a
|
|
directory entry
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
|
|
1.5.5 File Attributes
|
|
|
|
Table 1.9 describes the file attributes and how they are represented in the
|
|
attribute byte of the directory entry (offset 0BH). The attributes can be
|
|
inspected or changed with Function 43H (Get/Set File Attributes
|
|
[Chmod]).
|
|
|
|
Table 1.9
|
|
|
|
File Attributes
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Code Description
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
00H
|
|
|
|
Normal; can be read or written without restriction
|
|
|
|
01H
|
|
|
|
Read-only; cannot be opened for write; a file with the same name
|
|
cannot be created
|
|
|
|
02H Hidden; not found by directory search
|
|
|
|
04H System; not found by directory search
|
|
|
|
08H
|
|
|
|
VolumeID; only one file can have this attribute; it must be in the root
|
|
directory
|
|
|
|
10H Subdirectory
|
|
|
|
20H
|
|
|
|
Archive; set whenever the file is changed, or cleared by the Backup
|
|
command
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
The VolumeID (08H) and Subdirectory (10H) attributes cannot be changed
|
|
with Function 43H (Get/Set File Attributes [Chmod]).
|
|
|
|
1.6 Microsoft Networks
|
|
|
|
Microsoft Networks consists of a server and one or more workstations.
|
|
MS-DOS maintains an assign list that keeps track of which workstation
|
|
drives and devices have been redirected to the server. For a description of
|
|
operation and use of the network, see the Microsoft Networks 1.0
|
|
Manager's Guide and Microsoft Networks 1.0 User's Guide.
|
|
|
|
12
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
Table 1.10 lists the MS-DOS function requests for managing a Microsoft
|
|
Networks workstation.
|
|
|
|
Table 1.10
|
|
|
|
Microsoft Networks Function Requests
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
4409H
|
|
|
|
IOCtl Is Redirected
|
|
Block
|
|
|
|
Checks whether a drive letter refers to a local or
|
|
redirected drive
|
|
|
|
440AH
|
|
|
|
IOCtl Is Redirected
|
|
Handle
|
|
|
|
Checks whether a device name refers to a local or
|
|
redirected device
|
|
|
|
5E00H Get Machine Name Gets the network name of the workstation
|
|
|
|
5E02H Printer Setup
|
|
|
|
Defines a string of control characters to be added
|
|
at the beginning of each file that is sent to a
|
|
network printer
|
|
|
|
5F02H
|
|
|
|
Get Assign-List
|
|
Entry
|
|
|
|
Gets an entry from the assign list, which shows
|
|
the workstation drive letter or device name and
|
|
the net name of the directory or device on the
|
|
server to which the entry is reassigned
|
|
|
|
5F03H
|
|
|
|
Make Assign-List
|
|
Entry
|
|
|
|
Redirects a workstation drive or device to a
|
|
server directory or device
|
|
|
|
5F04H
|
|
|
|
Cancel Assign-List
|
|
Entry
|
|
|
|
Cancels the redirection of a workstation drive or
|
|
device to a server directory or device
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
|
|
1.7 National Language Support
|
|
|
|
National language support for this version of MS-DOS includes these
|
|
major features:
|
|
|
|
o Country-dependent information
|
|
|
|
o Support for national keyboard layouts
|
|
|
|
o Programming interfaces for national language support
|
|
|
|
o Utility commands
|
|
|
|
Country-dependent information is available on a per-country basis and
|
|
includes the following:
|
|
|
|
o Time, date, and currency
|
|
|
|
o Lowercase-to-uppercase character-conversion tables
|
|
|
|
o Collating sequence for character sorting
|
|
|
|
o Valid single-byte characters used in filenames
|
|
|
|
Keyboard support for different keyboard layouts is provided and
|
|
|
|
13
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
selectable.
|
|
|
|
Table 1.11 lists the MS-DOS national-language-support system calls that
|
|
allow applications to use the country-dependent information just
|
|
described.
|
|
|
|
Table 1.11
|
|
|
|
National Language-Support Function Requests
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
65H Get Extended Country Information
|
|
|
|
Returns standard country
|
|
information, pointer to uppercase
|
|
table, pointer to filename
|
|
uppercasing table, or pointer to
|
|
collating table
|
|
|
|
66H Get/Set Global Code Page
|
|
|
|
Gets or sets the code page used by
|
|
the kernel and all devices.
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
|
|
1.8 Miscellaneous System-Management Func-
|
|
tions
|
|
|
|
The remaining system calls manage other system functions and resources
|
|
such as drives, addresses, and the clock. Table 1.12 lists the MS-DOS func-
|
|
tion requests for managing miscellaneous system resources and operation.
|
|
|
|
Table 1.12
|
|
|
|
Miscellaneous System-Management Function Requests
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
0DH Reset Disk Empties all file buffers
|
|
|
|
0EH Select Disk Sets the default drive
|
|
|
|
19H Get Current Disk Returns the default drive
|
|
|
|
1AH Establishes the disk I/O buffer
|
|
|
|
Set Disk Transfer
|
|
Address
|
|
|
|
1BH Returns disk-format data
|
|
|
|
Get Default Drive Data
|
|
|
|
1CH Get Drive Data Returns disk-format data
|
|
|
|
25H Set Interrupt Vector Sets interrupt-handler address
|
|
|
|
29H Parse File Name Checks string for valid filename
|
|
|
|
2AH Get Date Returns system date
|
|
|
|
2BH Set Date Sets system date
|
|
|
|
2CH Get Time Returns system time
|
|
|
|
2DH Set Time Sets system time
|
|
|
|
2EH Set/Reset Verify Flag Turns disk verify on or off
|
|
|
|
14
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
2FH
|
|
|
|
Get Disk Transfer
|
|
Address
|
|
|
|
Returns system-disk-I/O-buffer address
|
|
|
|
|
|
30H Returns MS-DOS version number
|
|
|
|
Get MS-DOS Version
|
|
Number
|
|
|
|
33H CONTROL-C Check
|
|
|
|
Returns CONTROL-C check status
|
|
|
|
35H Get Interrupt Vector
|
|
|
|
Returns address of interrupt handler
|
|
|
|
36H Get Disk Free Space Returns disk-space data
|
|
|
|
38H Get/Set Country Data
|
|
|
|
Sets current country or retrieves country
|
|
information
|
|
|
|
54H Get Verify State Returns status of disk verify
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
|
|
1.9 Old System Calls
|
|
|
|
Most of the superseded system calls deal with files. Table 1.13 lists these
|
|
old calls and the function requests that have superseded them.
|
|
|
|
Although MS-DOS still includes these old system calls, they should not be
|
|
used unless a program must maintain backward-compatibility with earlier
|
|
versions of MS-DOS.
|
|
|
|
Table 1.13
|
|
|
|
Old System Calls and Their Replacements
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Old System Call Has Been Superseded By
|
|
|
|
Code Function Code Function
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
00H Terminate Program 4CH End Process
|
|
0FH Open File 3DH Open Handle
|
|
10H Close File 3EH Close Handle
|
|
11H Search for First Entry 4EH Find First File
|
|
12H Search for Next Entry 4FH Find Next File
|
|
13H Delete File 41H Delete Directory Entry
|
|
14H Sequential Read 3FH Read Handle
|
|
15H Sequential Write 40H Write Handle
|
|
16H Create File 3CH Create Handle
|
|
5AH Create Temporary File
|
|
5BH Create New File
|
|
17H Rename File 56H Change Directory Entry
|
|
21H Random Read 3FH Read Handle
|
|
22H Random Write 40H Write Handle
|
|
23H Get File Size 42H Move File Pointer
|
|
24H Set Relative Record 42H Move File Pointer
|
|
26H Create New PSP 4BH Load and Execute Program
|
|
27H Random Block Read 42H Move File Pointer
|
|
3FH Read Handle
|
|
|
|
15
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
28H Random Block Write 42H Move File Pointer
|
|
40H Write Handle
|
|
|
|
Code Interrupt Code Function
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
20H Program Terminate 4CH End Process
|
|
27H Terminate But Stay Resident 31H Keep Process
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
|
|
1.9.1 File Control Block (FCB)
|
|
|
|
The old file-related function requests require that a program maintain a
|
|
File Control Block (FCB) for each file; this control block contains such
|
|
information as a file's name, size, record length, and pointer to current
|
|
record. MS-DOS does most of this housekeeping for the newer, handle-
|
|
oriented function requests.
|
|
|
|
Some descriptions of the old function requests refer to unopened and
|
|
opened FCBs. An unopened FCB contains only a drive specifier and
|
|
filename. An opened FCB contains all fields filled by Function 0FH (Open
|
|
File).
|
|
|
|
The Program Segment Prefix (PSP) includes room for two FCBs at offsets
|
|
5CH and 6CH. For a description of how to use the PSP and FCB calls, see
|
|
Chapter 4, "MS-DOS Control Blocks and Work Areas," Table 1.14
|
|
describes the FCB fields.
|
|
|
|
Table 1.14
|
|
|
|
Format of the File Control Block (FCB)
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Offset
|
|
Hex Dec Bytes Field
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
00H 0 1 Drive Number
|
|
01H 1 8 Filename
|
|
09H 9 3 Extension
|
|
0CH 12 2 Current Block
|
|
|
|
0EH 14 2 Record Size
|
|
10H 16 4 File Size
|
|
14H 20 2 Date of Last Write
|
|
16H 22 2 Time of Last Write
|
|
|
|
18H 24 8 Reserved
|
|
20H 32 1 Current Record
|
|
21H 33 4 Relative Record
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
|
|
|
|
16
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
|
|
Fields of the FCB
|
|
|
|
Drive Number (offset 00H): Specifies the disk drive; 1 means drive A and 2
|
|
means drive B. If you use the FCB to create or open a file, you can set this
|
|
field to 0 to specify the default drive; Function 0FH (Open File) sets the
|
|
field to the number of the default drive.
|
|
|
|
Filename (offset 01H): Eight characters, left-aligned and padded (if neces-
|
|
sary) with blanks. If you specify a reserved device name (such as PRN), do
|
|
not put a colon at the end.
|
|
|
|
Extension (offset 09H): Three characters, left-aligned and padded (if neces-
|
|
sary) with blanks. This field can be all blanks (no extension).
|
|
|
|
Current Block (offset 0CH): Points to the block (group of 128 records) that
|
|
contains the current record. This field and the Current Record field (offset
|
|
1FH) make up the record pointer. This field is set to zero by the Open File
|
|
system call.
|
|
|
|
Record Size (offset 0EH): The size of a logical record, in bytes. Set to 128
|
|
by the Open File system call. If the record size is not 128 bytes, you must
|
|
set this field after opening the file.
|
|
|
|
File Size (offset 0FH): The size of the file, in bytes. The first word of this
|
|
4-byte field is the low-order part of the size.
|
|
|
|
Date of Last Write (offset 13H): The date the file was created or last
|
|
updated. The year, month, and day are mapped into two bytes as follows:
|
|
|
|
Off set 14H Offset 13H
|
|
|Y|Y|Y|Y|Y|Y|Y|M| |M|M|M|D|D|D|D|D|
|
|
15 9 8 5 4 0
|
|
|
|
Time of Last Write (offset 15H): The time the file was created or last
|
|
updated. The hour, minutes, and seconds are mapped into two bytes as
|
|
follows:
|
|
|
|
Offset 16H Offset 15H
|
|
|H|H|H|H|H|M|M|M| |M|M|M|S|S|S|S|S|
|
|
15 11 10 5 4 0
|
|
|
|
Reserved (offset 17H): These fields are reserved for use by MS-DOS.
|
|
|
|
Current Record (offset 1FH): Points to one of the 128 records in the
|
|
current block. This field and the Current Block field (offset 0CH) make up
|
|
the record pointer. The Open File system call does not initialize this field.
|
|
You must set it before doing a sequential read or write to the file.
|
|
|
|
|
|
|
|
17
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
Relative Record (offset 20H): Points to the currently selected record, count-
|
|
ing from the beginning of the file (starting with 0). The Open File system
|
|
call does not initialize this field. You must set it before doing a random
|
|
read or write to the file. If the record size is less than 64 bytes, both words
|
|
of this field are used; if the record size is 64 bytes or more, only the first
|
|
three bytes are used.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
Note
|
|
|
|
If you use the FCB at offset 5CH of the Program Segment Prefix, the
|
|
last byte of the Relative Record field is the first byte of the unformat-
|
|
ted parameter area that starts at offset 80H. This is the default Disk
|
|
Transfer Area.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
|
|
Extended FCB
|
|
|
|
The Extended File Control Block is used to create or search for directory
|
|
entries of files with special attributes. It adds the following 7-byte prefix to
|
|
the FCB:
|
|
|
|
Name Bytes Offset
|
|
|
|
_ ________________________________________________________________
|
|
|
|
Flag byte (FFH) 1 07H
|
|
Reserved 5 06H
|
|
Attribute byte 1 01H
|
|
|
|
_ ________________________________________________________________
|
|
|
|
File attributes are described earlier in this chapter in Section 1.5.5, "File
|
|
Attributes."
|
|
|
|
_ ________________________________________________________________
|
|
|
|
Note
|
|
|
|
You must remember to point to the beginning of the extended FCB if
|
|
you are using Functions 0FH-16H with extended FCBs.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
|
|
|
|
18
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
|
|
1.10 Using the System Calls
|
|
|
|
The remainder of this chapter describes how to use the system calls in
|
|
application programs, and it lists the calls in numeric and alphabetic
|
|
order, describing each call in detail.
|
|
|
|
1.10.1 Issuing an Interrupt
|
|
|
|
MS-DOS reserves Interrupts 28H through 3FH for its own use, and main-
|
|
tains the table of interrupt-handler addresses (the vector table) in loca-
|
|
tions 80H-FCH. Also, in case you need to write your own routines for
|
|
three particular MS-DOS interrupt handlers (Program Terminate,
|
|
CONTROL-C, and Critical Error), this chapter includes descriptions of each.
|
|
Function requests have superseded most of these interrupts.
|
|
|
|
To issue an interrupt, move any required data into the registers and give
|
|
the INT instruction with the number of the interrupt you want.
|
|
|
|
1.10.2 Calling a Function Request
|
|
|
|
A function request is an MS-DOS routine for managing system resources.
|
|
Use the following procedure to call a function request:
|
|
|
|
1. Move any required data into the registers.
|
|
|
|
2. Move the function number into AH.
|
|
|
|
3. Move the action code, if required, into AL.
|
|
|
|
4. Issue Interrupt 21H.
|
|
|
|
|
|
1.10.3 Using the Calls from a High-Level Language
|
|
|
|
The system calls can be executed from any high-level language whose
|
|
modules can be linked with assembly-language modules. In addition to this
|
|
linking technique, you can:
|
|
|
|
o Use the DOSXQQ function of Pascal-86 to call a function request
|
|
directly.
|
|
|
|
o Use the CALL statement or USER function to execute the required
|
|
assembly-language code from the BASIC interpreter.
|
|
|
|
|
|
|
|
19
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
|
|
1.10.4 Treatment of Registers
|
|
|
|
When MS-DOS takes control after a function request, it switches to an
|
|
internal stack, and preserves any registers not used to return information
|
|
(except AX). The calling program's stack must be large enough to accom-
|
|
modate the interrupt system\(emat least 128 bytes in addition to other
|
|
needs.
|
|
|
|
1.10.5 Handling Errors
|
|
|
|
Most of the function requests introduced with version 2.0 or later set the
|
|
Carry flag if there is an error, identifying the specific error by returning a
|
|
number in the AX register. Table 1.15 lists these error codes and their
|
|
meanings.
|
|
|
|
Table 1.15
|
|
|
|
Error Codes Returned in AX
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Code Meaning
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
1 Invalid function code
|
|
2 File not found
|
|
3 Path not found
|
|
4 Too many open files (no open handles left)
|
|
5 Access denied
|
|
6 Invalid handle
|
|
7 Memory control blocks destroyed
|
|
8 Insufficient memory
|
|
9 Invalid memory block address
|
|
|
|
10 Invalid environment
|
|
11 Invalid format
|
|
12 Invalid access code
|
|
13 Invalid data
|
|
14 Reserved
|
|
15 Invalid drive
|
|
16 Attempt to remove the current directory
|
|
17 Not same device
|
|
18 No more files
|
|
19 Disk is write-protected
|
|
|
|
20 Bad disk unit
|
|
21 Drive not ready
|
|
22 Invalid disk command
|
|
23 CRC error
|
|
24 Invalid length (disk operation)
|
|
25 Seek error
|
|
26 Not an MS-DOS disk
|
|
27 Sector not found
|
|
28 Out of paper
|
|
29 Write fault
|
|
|
|
20
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
|
|
30 Read fault
|
|
31 General failure
|
|
32 Sharing violation
|
|
33 Lock violation
|
|
34 Wrong disk
|
|
35 FCB unavailable
|
|
36-49 Reserved
|
|
|
|
50 Network request not supported
|
|
51 Remote computer not listening
|
|
52 Duplicate name on network
|
|
53 Network name not found
|
|
54 Network busy
|
|
55 Network device no longer exists
|
|
56 Net BIOS command limit exceeded
|
|
57 Network adapter hardware error
|
|
58 Incorrect response from network
|
|
59 Unexpected network error
|
|
|
|
60 Incompatible remote adapter
|
|
61 Print queue full
|
|
62 Queue not full
|
|
63 Not enough space for print file
|
|
64 Network name was deleted
|
|
65 Access denied
|
|
66 Network device type incorrect
|
|
67 Network name not found
|
|
68 Network name limit exceeded
|
|
69 Net BIOS session limit exceeded
|
|
|
|
70 Temporarily paused
|
|
71 Network request not accepted
|
|
72 Print or disk redirection is paused
|
|
73-79 Reserved
|
|
|
|
80 File exists
|
|
81 Reserved
|
|
82 Cannot make
|
|
83 Interrupt 24 failure
|
|
84 Out of structures
|
|
85 Already assigned
|
|
86 Invalid password
|
|
87 Invalid parameter
|
|
88 Net write fault
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
To handle error conditions, put the following statement immediately after
|
|
calls that return errors:
|
|
|
|
JC <error>
|
|
|
|
<Error> represents the label of an error-handling routine that gets the
|
|
specific error condition by checking the value in AX. This routine then
|
|
|
|
21
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
takes appropriate action.
|
|
|
|
Some of the older system calls return a value in a register that specifies
|
|
whether the operation was successful. To handle such errors, check the
|
|
error code and take the appropriate action.
|
|
|
|
Extended Error Codes
|
|
|
|
Versions of MS-DOS after 2.0 have added new error messages. Any pro-
|
|
grams that use the older system calls cannot use these new error messages.
|
|
To avoid incompatibility, MS-DOS maps these new error codes to the old
|
|
error code that most closely matches the new one.
|
|
|
|
Function 59H (Get Extended Error) has been added so that these new calls
|
|
can be used. It provides as much detail as possible about the most recent
|
|
error code returned by MS-DOS. The description of Function 59H lists the
|
|
new, more detailed error codes and shows how to use this function request.
|
|
|
|
1.10.6 System Call Descriptions
|
|
|
|
Most system calls require that you move information into one or more
|
|
registers before issuing the call that returns information in the registers.
|
|
The description of each system call in this chapter includes the following:
|
|
|
|
o A diagram of the 8088 registers that shows their contents before
|
|
and after the system call
|
|
|
|
o A more complete description of the register contents required
|
|
before the system call
|
|
|
|
o A description of the processing performed
|
|
|
|
o A more complete description of the register contents after the sys-
|
|
tem call
|
|
|
|
o An example of how to use the system call
|
|
|
|
The following figure is a sample illustration of the 8088 registers, showing
|
|
how the information is presented. Shaded areas indicate that the register
|
|
receives or returns information used by the call.
|
|
|
|
_ _____________________
|
|
|
|
|
|
22
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
_ _____________________
|
|
|
|
|
|
Figure 1.1 Example of the 8088 Registers
|
|
|
|
|
|
1.10.6.1 Sample Programs
|
|
|
|
The sample programs show only data declarations and the code that you
|
|
need to use the system calls. Unless stated otherwise, each example
|
|
assumes a common program skeleton that defines the segments and
|
|
returns control to MS-DOS. Each sample program is intended to be exe-
|
|
cuted as a .com file. Figure 1.2 shows a complete sample program. The
|
|
unshaded portion shows what appears in this chapter; the shaded portions
|
|
are the common skeleton.
|
|
|
|
------------------------------------------------------------
|
|
code segment
|
|
assume cs:code,ds:code,es:nothing,ss:nothing
|
|
org 100H
|
|
start: jmp begin
|
|
;
|
|
filename db "b:\textfile.asc",0
|
|
buffer db 129 dup (?)
|
|
handle dw ?
|
|
;
|
|
begin: open_handle filename,0 ; Open the file
|
|
jc error_open ; Routine not shown
|
|
mov handle,ax ; Save handle
|
|
read_line: read_handle handle,buffer,128 ; Read 128 bytes
|
|
jc error_read ; Routine not shown
|
|
cmp ax,0 ; End of file?
|
|
je return ; Yes, go home
|
|
mov bx,ax ; No, AX bytes read
|
|
mov buffer[bx],"$" ; To terminate string
|
|
display buffer ; See Function 09H
|
|
jmp read_line ; Get next 128 bytes
|
|
|
|
return: end_process 0 ; Return to MS-DOS
|
|
last_inst: ; To mark next byte
|
|
;
|
|
code ends
|
|
end start
|
|
------------------------------------------------------------
|
|
|
|
|
|
Figure 1.2 Sample Program with Common Skeleton
|
|
|
|
A macro has been defined for each system call to allow the examples to be
|
|
more complete programs, rather than isolated uses of the system calls.
|
|
These macros, plus some general-purpose ones, are used in the sample pro-
|
|
grams. For instance, the sample program in the preceding figure includes
|
|
four such macros: open_handle, read_handle, display, and end_process.
|
|
|
|
23
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
All the macro definitions are listed at the end of this chapter.
|
|
|
|
The macros assume the environment for a .com program as described in
|
|
Chapter 4; in particular, they assume that all the segment registers con-
|
|
tain the same value. To conserve space, the macros generally leave error
|
|
checking to the main code and do not protect registers. This keeps the
|
|
macros short, yet useful. You may find that such macros are a convenient
|
|
way to include system calls in your assembly-language programs.
|
|
|
|
1.10.6.2 Error Handling in Sample Programs
|
|
|
|
Whenever a system call returns an error code, the sample program shows a
|
|
test for the error condition and a jump to an error routine. To conserve
|
|
space, the error routines themselves aren't shown. Some error routines
|
|
might simply display a message and continue processing. For more serious
|
|
errors, the routine might display a message and end the program (perform-
|
|
ing any required housekeeping, such as closing files).
|
|
|
|
Tables 1.16 through 1.19 list the Interrupts and Function Requests in
|
|
numeric and alphabetic order.
|
|
|
|
Table 1.16
|
|
|
|
MS-DOS Interrupts, Numeric Order
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Interrupt Description
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
20H Program Terminate
|
|
21H Function Request
|
|
22H Terminate Process Exit Address
|
|
23H CONTROL-C Handler Address
|
|
24H Critical-Error-Handler Address
|
|
25H Absolute Disk Read
|
|
26H Absolute Disk Write
|
|
27H Terminate But Stay Resident
|
|
28H-3FH Reserved
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Table 1.17
|
|
|
|
MS-DOS Interrupts, Alphabetic Order
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Description Interrupt
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Absolute Disk Read 25H
|
|
Absolute Disk Write 26H
|
|
CONTROL-C Handler Address 23H
|
|
Critical-Error-Handler Address 24H
|
|
Function Request 21H
|
|
Program Terminate 20H
|
|
|
|
24
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
Reserved 28H-3FH
|
|
Terminate Process Exit Address 22H
|
|
Terminate But Stay Resident 27H
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Table 1.18
|
|
|
|
MS-DOS Function Requests, Numeric Order
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Function Description
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
00H Terminate Program
|
|
|
|
01H Read Keyboard And Echo
|
|
|
|
02H Display Character
|
|
|
|
03H Auxiliary Input
|
|
|
|
04H Auxiliary Output
|
|
|
|
05H Print Character
|
|
|
|
06H Direct Console I/O
|
|
|
|
07H Direct Console Input
|
|
|
|
08H Read Keyboard
|
|
|
|
09H Display String
|
|
|
|
0AH Buffered Keyboard Input
|
|
|
|
0BH Check Keyboard Status
|
|
|
|
0CH Flush Buffer, Read Keyboard
|
|
|
|
0DH Reset Disk
|
|
|
|
0EH Select Disk
|
|
|
|
0FH Open File
|
|
|
|
10H Close File
|
|
|
|
11H Search For First Entry
|
|
|
|
12H Search For Next Entry
|
|
|
|
13H Delete File
|
|
|
|
14H Sequential Read
|
|
|
|
15H Sequential Write
|
|
|
|
16H Create File
|
|
|
|
17H Rename File
|
|
|
|
18H Reserved
|
|
|
|
19H Get Current Disk
|
|
|
|
1AH Set Disk Transfer Address
|
|
|
|
1BH Get Default Drive Data
|
|
|
|
1CH Get Drive Data
|
|
|
|
1DH-20H Reserved
|
|
|
|
21H Random Read
|
|
|
|
25
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
22H Random Write
|
|
|
|
23H Get File Size
|
|
|
|
24H Set Relative Record
|
|
|
|
25H Set Interrupt Vector
|
|
|
|
26H Create New PSP
|
|
|
|
27H Random Block Read
|
|
|
|
28H Random Block Write
|
|
|
|
29H Parse File Name
|
|
|
|
2AH Get Date
|
|
|
|
2BH Set Date
|
|
|
|
2CH Get Time
|
|
|
|
2DH Set Time
|
|
|
|
2EH Set/Reset Verify Flag
|
|
|
|
2FH Get Disk Transfer Address
|
|
|
|
30H Get MS-DOS Version Number
|
|
|
|
31H Keep Process
|
|
|
|
32H Reserved
|
|
|
|
33H CONTROL-C Check
|
|
|
|
34H Reserved
|
|
|
|
35H Get Interrupt Vector
|
|
|
|
36H Get Disk Free Space
|
|
|
|
37H Reserved
|
|
|
|
38H Get/Set Country Data
|
|
|
|
39H Create Directory
|
|
|
|
3AH Remove Directory
|
|
|
|
3BH Change Current Directory
|
|
|
|
3CH Create Handle
|
|
|
|
3DH Open Handle
|
|
|
|
3EH Close Handle
|
|
|
|
3FH Read Handle
|
|
|
|
40H Write Handle
|
|
|
|
41H Delete Directory Entry (Unlink)
|
|
|
|
42H Move File Pointer
|
|
|
|
43H Get/Set File Attributes (Chmod)
|
|
|
|
4400H,4401H IOCtl Data
|
|
|
|
4402H,4403H IOCtl Character
|
|
|
|
4404H,4405H IOCtl Block
|
|
|
|
4406H,4407H IOCtl Status
|
|
|
|
4408H IOCtl Is Changeable
|
|
|
|
4409H IOCtl Is Redirected Block
|
|
|
|
26
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
440AH IOCtl Is Redirected Handle
|
|
|
|
440BH IOCtl Retry
|
|
|
|
440CH Generic IOCtl (for code page functions)
|
|
|
|
440DH Generic IOCtl (for devices)
|
|
|
|
440EH Get IOCtl Drive Map
|
|
|
|
440FH Set IOCtl Drive Map
|
|
|
|
45H Duplicate File Handle
|
|
|
|
46H Force Duplicate File Handle
|
|
|
|
47H Get Current Directory
|
|
|
|
48H Allocate Memory
|
|
|
|
49H Free Allocated Memory
|
|
|
|
4AH Set Block
|
|
|
|
4BH Load and Execute Program
|
|
|
|
4B03H Load Overlay
|
|
|
|
4CH End Process
|
|
|
|
4DH Get Return Code of Child Process
|
|
|
|
4EH Find First File
|
|
|
|
4FH Find Next File
|
|
|
|
50H-53H Reserved
|
|
|
|
54H Get Verify State
|
|
|
|
55H Reserved
|
|
|
|
56H Change Directory Entry
|
|
|
|
57H Get/Set Date/Time of File
|
|
|
|
58H Get/Set Allocation Strategy
|
|
|
|
59H Get Extended Error
|
|
|
|
5AH Create Temporary File
|
|
|
|
5BH Create New File
|
|
|
|
5C00H Lock
|
|
|
|
5C01H Unlock
|
|
|
|
5DH Reserved
|
|
|
|
5E00H Get Machine Name
|
|
|
|
5E02H Printer Setup
|
|
|
|
5F02H Get Assign-List Entry
|
|
|
|
5F03H Make Assign-List Entry
|
|
|
|
5F04H Cancel Assign-List Entry
|
|
|
|
60H-61H Reserved
|
|
|
|
62H Get PSP
|
|
|
|
63H,64H Reserved
|
|
|
|
65H Get Extended Country Information
|
|
|
|
66H Get/Set Global Code Page
|
|
|
|
27
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
67H Set Handle Count
|
|
|
|
68H Commit File
|
|
|
|
69H-7FH Reserved
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Table 1.19
|
|
|
|
MS-DOS Function Requests, Alphabetic Order
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Description Interrupt
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
Allocate Memory 48H
|
|
|
|
Auxiliary Input 03H
|
|
|
|
Auxiliary Output 04H
|
|
|
|
Buffered Keyboard Input 0AH
|
|
|
|
Cancel Assign-List Entry 5F04H
|
|
|
|
Change Current Directory 3BH
|
|
|
|
Change Directory Entry 56H
|
|
|
|
Check Keyboard Status 0BH
|
|
|
|
Close File 10H
|
|
|
|
Close Handle 3EH
|
|
|
|
Commit FIle 68H
|
|
|
|
CONTROL-C Check 33H
|
|
|
|
Create Directory 39H
|
|
|
|
Create File 16H
|
|
|
|
Create Handle 3CH
|
|
|
|
Create New File 5BH
|
|
|
|
Create New PSP 26H
|
|
|
|
Create Temporary File 5AH
|
|
|
|
Delete Directory Entry (Unlink) 41H
|
|
|
|
Delete File 13H
|
|
|
|
Direct Console I/O 06H
|
|
|
|
Direct Console Input 07H
|
|
|
|
Display Character 02H
|
|
|
|
Display String 09H
|
|
|
|
Duplicate File Handle 45H
|
|
|
|
End Process 4CH
|
|
|
|
Find First File 4EH
|
|
|
|
Find Next File 4FH
|
|
|
|
Flush Buffer, Read Keyboard 0CH
|
|
|
|
Force Duplicate File Handle 46H
|
|
|
|
|
|
28
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
Free Allocated Memory 49H
|
|
|
|
Generic IOCtl (for devices) 440DH
|
|
|
|
Generic IOCtl (for code page functions) 440CH
|
|
|
|
Get Assign-List Entry 5F02H
|
|
|
|
Get Current Directory 47H
|
|
|
|
Get Current Disk 19H
|
|
|
|
Get Date 2AH
|
|
|
|
Get Default Drive Data 1BH
|
|
|
|
Get Disk Free Space 36H
|
|
|
|
Get Disk Transfer Address 2FH
|
|
|
|
Get Drive Data 1CH
|
|
|
|
Get Extended Country Information 65H
|
|
|
|
Get Extended Error 59H
|
|
|
|
Get File Size 23H
|
|
|
|
Get Interrupt Vector 35H
|
|
|
|
Get IOCtl Drive Map 440EH
|
|
|
|
Get Machine Name 5E00H
|
|
|
|
Get MS-DOS Version Number 30H
|
|
|
|
Get PSP 62H
|
|
|
|
Get Return Code of Child Process 4DH
|
|
|
|
Get Time 2CH
|
|
|
|
Get Verify State 54H
|
|
|
|
Get/Set Allocation Strategy 58H
|
|
|
|
Get/Set Country Data 38H
|
|
|
|
Get/Set Date/Time Of File 57H
|
|
|
|
Get/Set File Attributes (Chmod) 43H
|
|
|
|
Get/Set Global Code Page 66H
|
|
|
|
IOCtl Block 4404H,4405H
|
|
|
|
IOCtl Character 4402H,4403H
|
|
|
|
IOCtl Data 4400H,4401H
|
|
|
|
IOCtl Is Changeable 4408H
|
|
|
|
IOCtl Is Redirected Block 4409H
|
|
|
|
IOCtl Is Redirected Handle 440AH
|
|
|
|
IOCtl Retry 440BH
|
|
|
|
IOCtl Status 4406H,4407H
|
|
|
|
Keep Process 31H
|
|
|
|
Load and Execute Program 4BH
|
|
|
|
Load Overlay 4B03H
|
|
|
|
Lock 5C00H
|
|
|
|
Make Assign-List Entry 5F03H
|
|
|
|
29
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
Move File Pointer 42H
|
|
|
|
Open File 0FH
|
|
|
|
Open Handle 3DH
|
|
|
|
Parse File Name 29H
|
|
|
|
Print Character 05H
|
|
|
|
Printer Setup 5E02H
|
|
|
|
Random Block Read 27H
|
|
|
|
Random Block Write 28H
|
|
|
|
Random Read 21H
|
|
|
|
Random Write 22H
|
|
|
|
Read Handle 3FH
|
|
|
|
Read Keyboard 08H
|
|
|
|
Read Keyboard And Echo 01H
|
|
|
|
Remove Directory 3AH
|
|
|
|
Rename File 17H
|
|
|
|
Reserved 18H
|
|
|
|
Reserved 1DH-20H
|
|
|
|
Reserved 32H
|
|
|
|
Reserved 34H
|
|
|
|
Reserved 37H
|
|
|
|
Reserved 50H-53H
|
|
|
|
Reserved 55H
|
|
|
|
Reserved 5DH
|
|
|
|
Reserved 60H-61H
|
|
|
|
Reserved 63H, 64H
|
|
|
|
Reserved 69H-7FH
|
|
|
|
Reset Disk 0DH
|
|
|
|
Search for First Entry 11H
|
|
|
|
Search for Next Entry 12H
|
|
|
|
Select Disk 0EH
|
|
|
|
Sequential Read 14H
|
|
|
|
Sequential Write 15H
|
|
|
|
Set Block 4AH
|
|
|
|
Set Date 2BH
|
|
|
|
Set Disk Transfer Address 1AH
|
|
|
|
Set Handle Count 67H
|
|
|
|
Set Interrupt Vector 25H
|
|
|
|
Set IOCtl Drive Map 440FH
|
|
|
|
Set Relative Record 24H
|
|
|
|
Set Time 2DH
|
|
|
|
30
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
Set/Reset Verify Flag 2EH
|
|
|
|
Terminate Program 00H
|
|
|
|
Unlock 5C01H
|
|
|
|
Write Handle 40H
|
|
|
|
_ _________________________________________________________________________
|
|
|
|
A detailed description of each system call follows. These calls are listed in
|
|
numeric order, interrupts first, followed by function requests.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
Note
|
|
|
|
Unless stated otherwise, in the system call descriptions\(emboth text and
|
|
code\(emall numbers are in hexadecimal.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
|
|
1.11 Interrupts
|
|
|
|
The following pages describe Interrupts 20H-27H.
|
|
|
|
|
|
31
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
|
|
Program Terminate (Interrupt 20H)
|
|
|
|
Call:
|
|
|
|
CS
|
|
Segment address of Program Segment Prefix
|
|
|
|
Return:
|
|
|
|
None
|
|
|
|
|
|
|
|
Comments:
|
|
|
|
Interrupt 20H terminates the current process and returns control to its
|
|
parent process. It also closes all open file handles and clears the disk cache.
|
|
When this interrupt is issued, CS must contain the segment address of the
|
|
Program Segment Prefix.
|
|
|
|
Interrupt 20H is provided only for compatibility with MS-DOS versions
|
|
prior to 2.0. New programs should use Function 4CH (End Process),
|
|
which permits returning a completion code to the parent process and does
|
|
not require CS to contain the segment address of the Program Segment
|
|
Prefix.
|
|
|
|
The following exit addresses are restored from the Program Segment
|
|
Prefix:
|
|
|
|
Offset
|
|
Exit Address
|
|
_ ________________________________________________________________
|
|
|
|
0AH Program terminate
|
|
|
|
0EH CONTROL-C
|
|
|
|
12H Critical error
|
|
|
|
All file buffers are flushed to disk.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
32
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
Note
|
|
|
|
You should close all files that have changed in length before issuing
|
|
this interrupt. If you do not close a changed file, its length may not be
|
|
recorded correctly in the directory. See Functions 10H and 3EH for a
|
|
description of the Close File system calls. If sharing is loaded, you
|
|
should remove all locks before using Interrupt 20H. See Function 5CH
|
|
(Lock) for more information.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
|
|
Macro Definition:
|
|
|
|
|
|
terminate macro
|
|
int 20H
|
|
endm
|
|
|
|
|
|
Example:
|
|
|
|
The following program displays a message and returns to MS-DOS. It uses
|
|
only the opening portion of the sample program skeleton shown in Figure
|
|
1.2:
|
|
|
|
message db "displayed by INT20H example". 0DH, 0AH, "$"
|
|
;
|
|
begin: display message ;see Function 09H
|
|
terminate ;THIS INTERRUPT
|
|
code ends
|
|
end start
|
|
|
|
|
|
|
|
33
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
|
|
Function Request (Interrupt 21H)
|
|
|
|
Call:
|
|
|
|
AH
|
|
Function number
|
|
|
|
Other registers
|
|
As specified in individual function
|
|
|
|
Return:
|
|
|
|
None.
|
|
|
|
|
|
|
|
Comments:
|
|
|
|
As specified in individual function. Interrupt 21H causes MS-DOS to carry
|
|
out the function request whose number is in AH. See Section 1.12, "Func-
|
|
tion Requests," for a description of the MS-DOS functions.
|
|
|
|
Example:
|
|
|
|
To call the Get Time function:
|
|
|
|
mov ah,2CH ;Get Time is Function 2CH
|
|
int 21H ;MS-DOS function request
|
|
|
|
|
|
|
|
34
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
|
|
Terminate Process Exit Address (Interrupt
|
|
22H)
|
|
|
|
This interrupt may be issued only by MS-DOS; user programs must never
|
|
issue it. If you must write your own terminate interrupt handler, use
|
|
Function 35H (Get Interrupt Vector) to get the address of the standard
|
|
routine, save the address, then use Function 25H (Set Interrupt Vector) to
|
|
change the Interrupt 22H entry in the vector table so that it points to your
|
|
routine.
|
|
|
|
When a program terminates, MS-DOS transfers control to the routine that
|
|
starts at the address in the Interrupt 22H entry in the vector table. When
|
|
MS-DOS creates a program segment, it copies this address into the Pro-
|
|
gram Segment Prefix, starting at offset 0AH.
|
|
|
|
|
|
35
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
|
|
CONTROL-C Handler Address (Interrupt 23H)
|
|
|
|
When you type CONTROL-C or CONTROL-BREAK (on IBM-compatibles),
|
|
MS-DOS transfers control as soon as possible to the routine that starts at
|
|
the address in the Interrupt 23H entry in the vector table. When MS-DOS
|
|
creates a program segment, it copies the address currently in the interrupt
|
|
table into the Program Segment Prefix, starting at offset 0EH.
|
|
|
|
This interrupt may be issued only by MS-DOS; user programs must never
|
|
issue it. If you must write your own CONTROL-C interrupt handler, use
|
|
Function Request 35H (Get Interrupt Vector) to get the address of the
|
|
standard routine, save the address, then use Function Request 25H (Set
|
|
Interrupt Vector) to change the Interrupt 23H entry in the vector table to
|
|
point to your routine.
|
|
|
|
If the CONTROL-C routine preserves all registers, it can end with an IRET
|
|
instruction (return from interrupt) to continue program execution. If a
|
|
user-written interrupt program returns with a long return, the program
|
|
uses the carry flag to determine whether or not the program will abort. If
|
|
the carry flag is set, it will abort; otherwise, execution will continue as
|
|
with a return by IRET.
|
|
|
|
If a user-written CONTROL-BREAK routine interrupts function calls 09H,
|
|
0AH, or buffered I/O, and if it continues execution with an IRET, then
|
|
I/O continues from the start of the line. MS-DOS always outputs a
|
|
CONTROL-C to the screen when it issues an Interrupt 23H. There is no way
|
|
to turn this off.
|
|
|
|
When the interrupt occurs, all registers are set to the value they had when
|
|
the original call to MS-DOS was made. There are no restrictions on what
|
|
a CONTROL-C handler can do\(emincluding calling MS-DOS functions\(emas
|
|
long as the program restores the registers.
|
|
|
|
If a CONTROL-C interrupts Function 09H or 0AH (Display String or
|
|
Buffered Keyboard Input), the three-byte sequence 03H-0DH-0AH (usually
|
|
displayed as C followed by a carriage-return) is sent to the display and the
|
|
function resumes at the beginning of the next line.
|
|
|
|
Suppose a program uses Function 4BH (Load and Execute Program) to
|
|
create a second Program Segment Prefix and execute a second program,
|
|
which then changes the CONTROL-C address in the vector table. MS-DOS
|
|
restores this CONTROL-C vector to its original value before returning con-
|
|
trol to the calling program.
|
|
|
|
|
|
36
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
|
|
Critical-Error-Handler Address (Interrupt 24H)
|
|
|
|
If a critical error occurs during execution of an I/O function request (this
|
|
often means a fatal disk error), MS-DOS transfers control to the routine at
|
|
the address in the Interrupt 24H entry in the vector table. When MS-DOS
|
|
creates a program segment, it copies this address into the Program Seg-
|
|
ment Prefix, starting at offset 12H.
|
|
|
|
This interrupt may be issued only by MS-DOS; user programs must never
|
|
issue it. If you must write your own critical-error interrupt handler, use
|
|
Function 35H (Get Interrupt Vector) to get the address of the standard
|
|
routine, save the address, then use Function 25H (Set Interrupt Vector) to
|
|
change the Interrupt 24H entry in the vector table to point to your rou-
|
|
tine.
|
|
|
|
MS-DOS does not issue Interrupt 24H if a failure occurs during execution
|
|
of Interrupt 25H (Absolute Disk Read) or Interrupt 26H (Absolute Disk
|
|
Write). A command.com error routines handles these errors. This routine
|
|
retries the disk operation, then gives you the choice of aborting the opera-
|
|
tion, retrying it, allowing the system call to fail and the application pro-
|
|
cess to continue, or ignoring the error.
|
|
|
|
The following topics describe the requirements of an Interrupt 24H rou-
|
|
tine, including the error codes, registers, and stack.
|
|
|
|
1.11.1 Conditions upon Entry
|
|
|
|
After retrying an I/O error five times, MS-DOS issues Interrupt 24H,
|
|
unless a File Allocation Table (FAT) or directory sector is involved. In
|
|
those cases, DOS performs three retries. The interrupt handler receives
|
|
control with interrupts disabled. AX and DI contain error codes, and BP
|
|
contains the offset (to the segment address in SI) of a Device Header con-
|
|
trol block that describes the device on which the error occurred.
|
|
|
|
1.11.2 Requirements for an Interrupt 24H Handler
|
|
|
|
To issue the "Abort, Retry, Fail or Ignore" prompt to a user, a user-
|
|
written critical-error handler should first push the flags and execute a FAR
|
|
call to the address of the standard Interrupt 24H handler (the user pro-
|
|
gram that changed the Interrupt 24H vector also should have saved this
|
|
address). After a user responds to the prompt, MS-DOS returns control to
|
|
the user-written routine.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
Note
|
|
|
|
|
|
37
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
There are source applications which will have trouble handling critical
|
|
errors, since this changes the stack frame.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
The error handler can then do its processing, but before it does anything
|
|
else it must preserve BX, CX, DX, DS, ES, SS, and SP. Also, the error
|
|
handler may use only function calls 01-0CH (inclusive) and 59H (if it uses
|
|
any others, the error handler destroys the MS-DOS stack and leaves
|
|
MS-DOS in an unstable state). The contents of the Device Header should
|
|
not be changed.
|
|
|
|
It is recommended that Interrupt 24H routine fail critical errors and let
|
|
the application test for an extended error code when the Interrupt 21H
|
|
routine returns.
|
|
|
|
User Stack
|
|
|
|
This call uses the user stack that contains the following (starting with the
|
|
top of the stack):
|
|
|
|
IP MS-DOS registers from issuing Interrupt 24H
|
|
CS
|
|
FLAGS
|
|
|
|
AX User registers at time of original
|
|
BX INT 21H
|
|
CX
|
|
DX
|
|
SI
|
|
DI
|
|
BP
|
|
DS
|
|
ES
|
|
|
|
IP From the original INT 21H
|
|
CS from the user to MS-DOS
|
|
FLAGS
|
|
|
|
The registers are set such that if the user-written error handler issues an
|
|
IRET, MS-DOS responds according to the value in AL:
|
|
|
|
AL
|
|
Action
|
|
_ ________________________________________________________________
|
|
|
|
0 Ignore the error.
|
|
|
|
1 Retry the operation.
|
|
|
|
2 Abort the program by issuing Interrupt 23H.
|
|
|
|
|
|
|
|
38
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
3 Fail the system call that is in progress.
|
|
|
|
Note that the ignore option may cause unexpected results, such as causing
|
|
MS-DOS to behave as if an operation had completed successfully.
|
|
|
|
Disk Error Code in AX
|
|
|
|
If bit 7 of AH is 0, the error occurred on a disk drive. AL contains the fail-
|
|
ing drive (0=A, 1=B, etc.). Bit 0 of AH specifies whether the error
|
|
occurred during a read or write operation (0=read, 1=write), and bits 1
|
|
and 2 of AH identify the area of the disk where the error occurred:
|
|
|
|
Bits 1-2
|
|
Location of error
|
|
_ ________________________________________________________________
|
|
|
|
00 MS-DOS area
|
|
|
|
01 File Allocation Table
|
|
|
|
10 Directory
|
|
|
|
11 Data area
|
|
|
|
Bits 3-5 of AH specify valid responses to the error prompt:
|
|
|
|
Bit Value Response
|
|
|
|
_ ________________________________________________________________
|
|
|
|
3 0 Fail not allowed
|
|
1 Fail allowed
|
|
|
|
4 0 Retry not allowed
|
|
1 Retry allowed
|
|
|
|
5 0 Ignore not allowed
|
|
1 Ignore allowed
|
|
|
|
_ ________________________________________________________________
|
|
|
|
If you specify Retry but it isn't allowed, MS-DOS changes it to Fail. If you
|
|
specify Ignore but it isn't allowed, MS-DOS changes it to Fail. If you
|
|
specify Fail but it isn't allowed, MS-DOS changes it to Abort. The Abort
|
|
response is always allowed.
|
|
|
|
Other Device Error Code in AX
|
|
|
|
If bit 7 of AH is 1, either the memory image of the File Allocation Table
|
|
(FAT) is bad or an error occurred on a character device. The device header
|
|
pointed to by BP:SI contains a WORD of attribute bits that identify the
|
|
type of device and, therefore, the type of error.
|
|
|
|
|
|
|
|
39
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
The word of attribute bits is at offset 04H of the Device Header. Bit 15
|
|
specifies the type of device (0=block, 1=character).
|
|
|
|
If bit 15 is 0 (block device), the error was a bad memory image of the FAT.
|
|
|
|
If bit 15 is 1 (character device), the error was on a character device. DI
|
|
contains the error code, the contents of AL are undefined, and bits 0-3 of
|
|
the attribute word have the following meaning:
|
|
|
|
Bit
|
|
Meaning if Set
|
|
_ ________________________________________________________________
|
|
|
|
0 Current standard input
|
|
|
|
1 Current standard output
|
|
|
|
2 Current null device
|
|
|
|
3 Current clock device
|
|
|
|
See Chapter 2, "MS-DOS Device Drivers," for a complete description of
|
|
the Device Header control block.
|
|
|
|
Error Code in DI
|
|
|
|
The high byte of DI is undefined. The low byte contains the following error
|
|
codes:
|
|
|
|
Error code
|
|
Description
|
|
_ ________________________________________________________________
|
|
|
|
0 Attempt to write on write-protected disk
|
|
|
|
1 Unknown unit
|
|
|
|
2 Drive not ready
|
|
|
|
3 Unknown command
|
|
|
|
4 CRC error in data
|
|
|
|
5 Bad drive request structure length
|
|
|
|
6 Seek error
|
|
|
|
7 Unknown media type
|
|
|
|
8 Sector not found
|
|
|
|
9 Printer out of paper
|
|
|
|
A Write fault
|
|
|
|
B Read fault
|
|
|
|
C General failure
|
|
|
|
A user-written Interrupt 24H handler can use Function 59H (Get Extended
|
|
|
|
40
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
Error) to get detailed information about the error that caused the inter-
|
|
rupt to be issued.
|
|
|
|
|
|
41
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
|
|
Absolute Disk Read (Interrupt 25H)
|
|
|
|
Call:
|
|
|
|
AL
|
|
Drive number
|
|
DS:BX
|
|
Disk Transfer Address
|
|
CX
|
|
Number of sectors
|
|
DX
|
|
Beginning relative sector
|
|
|
|
Return:
|
|
|
|
AL
|
|
Error code if CF=1
|
|
Flags
|
|
CF = 0 if successful
|
|
= 1 if not successful
|
|
|
|
|
|
Comments:
|
|
|
|
The registers must contain the following:
|
|
|
|
Register
|
|
Contents
|
|
_ ________________________________________________________________
|
|
|
|
AL Drive number (0=A, 1=B, etc.)
|
|
|
|
BX Offset of Disk Transfer Address (from segment address in DS)
|
|
|
|
CX Number of sectors to read
|
|
|
|
DX Beginning relative sector
|
|
|
|
_ ________________________________________________________________
|
|
|
|
Warning
|
|
|
|
Avoid using this function unless absolutely necessary. Instead, you
|
|
should access files through normal MS-DOS function requests. There
|
|
is no guarantee of upward compatibility for the Absolute Disk I/O in
|
|
future releases of MS-DOS.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
Interrupt 25H transfers control to the device driver and reads from the
|
|
disk to the Disk-Transfer Address the number of sectors specified in CX.
|
|
The interrupt has the same requirements as and processes identically to
|
|
|
|
42
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
Interrupt 26H (Absolute Disk Write), except that it reads data rather than
|
|
writes it. Also, since this interrupt does not check your input parameters
|
|
too closely, make sure they are reasonable. If you use unreasonable
|
|
parameters, you may get strange results or cause your system to crash.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
Note
|
|
|
|
This call destroys all registers except the segment registers. So before
|
|
issuing the interrupt, save any registers that your program uses.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
The system pushes the flags at the time of the call; they are still there upon
|
|
return. To prevent uncontrolled growth, be sure to pop the stack upon
|
|
return.
|
|
|
|
If the disk operation is successful, the Carry Flag (CF) is 0. If the disk
|
|
operation is not successful, CF is 1 and AL contains the MS-DOS error
|
|
code (see Interrupt 24H earlier in this section for the codes and their
|
|
meanings).
|
|
|
|
Macro Definition:
|
|
|
|
|
|
abs_disk_read macro disk,buffer,num_sectors,first_sector
|
|
mov al,disk
|
|
mov bx,offset buffer
|
|
mov cx,num_sectors
|
|
mov dx,first_sector
|
|
int 25H
|
|
popf
|
|
endm
|
|
|
|
|
|
Example:
|
|
|
|
The following program copies the contents of a single-sided disk in drive A
|
|
to the disk in drive B.
|
|
|
|
prompt db "Source in A, target in B",0DH,0AH
|
|
db "Any key to start. $"
|
|
first dw 0
|
|
buffer db 60 dup (512 dup (?)) ;60 sectors
|
|
;
|
|
begin: display prompt ;see Function 09H
|
|
read_kbd ;see Function 08H
|
|
mov cx,6 ;copy 6 groups of
|
|
;60 sectors
|
|
copy: push cx ;save the loop counter
|
|
abs_disk_read 0,buffer,60,first ;THIS INTERRUPT
|
|
|
|
43
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
abs_disk_write 1,buffer,60,first ;see INT 26H
|
|
add first,60 ;do the next 60 sectors
|
|
pop cx ;restore the loop counter
|
|
loop copy
|
|
|
|
|
|
|
|
44
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
|
|
Absolute Disk Write (Interrupt 26H)
|
|
|
|
Call:
|
|
|
|
AL
|
|
Drive number
|
|
DS:BX
|
|
Disk Transfer Address
|
|
CX
|
|
Number of sectors
|
|
DX
|
|
Beginning relative sector
|
|
|
|
Return:
|
|
|
|
AL
|
|
Error code if CF = 1
|
|
FLAGS
|
|
CF = 0 if successful
|
|
= 1 if not successful
|
|
|
|
|
|
Comments:
|
|
|
|
_ ________________________________________________________________
|
|
|
|
Warning
|
|
|
|
Avoid using this function unless absolutely necessary. Instead, you
|
|
should access files through normal MS-DOS function requests. There
|
|
is no guarantee of upward compatibility for the Absolute Disk I/O in
|
|
future releases of MS-DOS.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
The registers must contain the following:
|
|
|
|
Register
|
|
Contents
|
|
_ ________________________________________________________________
|
|
|
|
AL Drive number (0=A, 1=B, etc.)
|
|
|
|
BX Offset of Disk Transfer Address (from segment address in DS)
|
|
|
|
CX Number of sectors to write
|
|
|
|
DX Beginning relative sector
|
|
|
|
This interrupt transfers control to MS-DOS. The number of sectors
|
|
specified in CX is written from the Disk Transfer Address to the disk. Its
|
|
requirements and processing are identical to Interrupt 25H (Absolute Disk
|
|
|
|
45
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
Read), except data is written to the disk rather than read from it. Also,
|
|
since Interrupt 26H does not check your input parameters too closely,
|
|
make sure they are reasonable. If you use unreasonable parameters, you
|
|
may get strange results or cause your system to crash.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
Note
|
|
|
|
This call destroys all registers except the segment registers. So before
|
|
issuing the interrupt, be sure to save any registers your program uses.
|
|
|
|
_ ________________________________________________________________
|
|
|
|
The system pushes the flags at the time of the call; they are still there upon
|
|
return. To prevent uncontrolled growth, be sure to pop the stack upon
|
|
return.
|
|
|
|
If the disk operation is successful, the Carry Flag (CF) is 0. If the disk
|
|
operation is not successful, CF is 1 and AL contains the MS-DOS error
|
|
code (see Interrupt 24H for the codes and their meanings).
|
|
|
|
Macro Definition:
|
|
|
|
|
|
abs_disk_write macro disk,buffer,num_sectors,first_sector
|
|
mov al,disk
|
|
mov bx,offset buffer
|
|
mov cx,num_sectors
|
|
mov dx,first_sector
|
|
int 26H
|
|
popf
|
|
endm
|
|
|
|
|
|
Example:
|
|
|
|
The following program copies the contents of a single-sided disk in drive A
|
|
to the disk in drive B, verifying each write. It uses a buffer of 32K bytes.
|
|
|
|
off equ 0
|
|
on equ 1
|
|
;
|
|
prompt db "Source in A, target in B",0DH,0AH
|
|
db "Any key to start. $"
|
|
first dw 0
|
|
buffer db 60 dup (512 dup (?)) ;60 sectors
|
|
;
|
|
begin: display prompt ;see Function 09H
|
|
read_kbd ;see Function 08H
|
|
verify on ;see Function 2EH
|
|
mov cx,6 ;copy 6 groups of 60 sectors
|
|
|
|
46
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
copy: push cx ;save the loop counter
|
|
abs_disk_read 0,buffer,60,first ;see INT 25H
|
|
abs_disk_write 1,buffer,60,first ;THIS INTERRUPT
|
|
add first,60 ;do the next 60 sectors
|
|
pop cx ;restore the loop counter
|
|
loop copy
|
|
verify off ;see Function 2EH
|
|
|
|
|
|
|
|
47
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
Microsoft MS-DOS Programmer's Reference
|
|
|
|
_ _________________________________________________
|
|
|
|
|
|
Terminate But Stay Resident (Interrupt 27H)
|
|
|
|
Call:
|
|
|
|
CS:DX
|
|
Pointer to first byte following
|
|
last byte of code.
|
|
|
|
Return:
|
|
|
|
None
|
|
|
|
|
|
|
|
Comments:
|
|
|
|
This interrupt is provided only for compatibility with MS-DOS versions
|
|
prior to 2.0. Unless your resident program must be compatible with
|
|
MS-DOS versions before 2.0, you should use Function 31H (Keep Process)
|
|
to install it. Function 31H lets programs larger than 64K remain resident
|
|
and allows return information to be passed.
|
|
|
|
However, Interrupt 27H, which is often used to install device-specific inter-
|
|
rupt handlers, forces programs that are up to 64K to remain resident after
|
|
they terminate.
|
|
|
|
DX must contain the offset (from the segment address in CS) of the first
|
|
byte that follows the last byte of code in the program. When Interrupt
|
|
27H is executed, the program terminates and control returns to MS-DOS,
|
|
but the program is not overlaid by other programs. Files left open are not
|
|
closed. When the interrupt is called, CS must contain the segment
|
|
address of the Program Segment Prefix (the value of DS and ES when exe-
|
|
cution started).
|
|
|
|
.Exe programs that are loaded into high memory must not use this inter-
|
|
rupt. Similarly, since it restores the Interrupt 22H, 23H, and 24H vectors,
|
|
you should not use Interrupt 27H to install new CONTROL-C or critical-
|
|
error handlers.
|
|
|
|
|
|
48
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|
|
|
|
_ _ | | _ _
|
|
|
|
System Calls
|
|
|
|
_ ________________________
|
|
|
|
|
|
Macro Definition:
|
|
|
|
|
|
stay_resident macro last_instruc
|
|
mov dx,offset last_instruc
|
|
inc dx
|
|
int 27H
|
|
endm
|
|
|
|
|
|
Example:
|
|
|
|
Since the most common use of Interrupt 27H is to install a machine-
|
|
specific routine, there is no general example that applies. The macro
|
|
definition, however, shows the calling syntax.
|
|
|
|
1.12 Function Requests
|
|
|
|
The following pages describe function calls 00H-68H.
|
|
|
|
|
|
49
|
|
|
|
_ _ | | _ _
|
|
|
|
|
|
|