Microsoft Programmer's Library 1.3

home *** CD-ROM | disk | FTP | other *** search

/ Microsoft Programmer's Library 1.3 / Microsoft_Programmers_Library.7z / MPL / msdos / dos40ref.txt < prev next >

Wrap

Text File | 2013-11-08 | 710.1 KB | 19,304 lines

Microsoft MS-DOS Programmer's Reference ════════════════════════════════════════════════════════════════════════════ Microsoft(R) MS-DOS(R) Programmer's Reference Version 4.0 ════════════════════════════════════════════════════════════════════════════ Information in this document is subject to change without notice and does not represent a commitment on the part of Microsoft Corporation. The software described in this document is furnished under a license agreement or non-disclosure agreement. The software may be used or copied only in accordance with the terms of the agreement. It is against the law to copy the software on any medium except as specifically allowed in the license or non-disclosure agreement. No part of this manual may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording, for any purpose without the express written permission of Microsoft. (C) Copyright Microsoft Corporation, 1988. All rights reserved. Simultaneously published in the United States and Canada. Printed in the United States of America. Microsoft, the Microsoft logo, MS-DOS, and XENIX are registered trademarks of Microsoft Corporation. IBM, IBM Personal Computer, IBM PC, and PC-DOS are registered trademarks of International Business Machines Corporation. INTEL is a registered trademark of Intel Corporation. ──────────────────────────────────────────────────────────────────────────── Contents Chapter 1 System Calls 1.1 Introduction 1.1.1 System Calls That Have Been Superseded 1.1.2 How to Use This Manual 1.2 Standard Character Device I/O 1.3 Memory Management 1.4 Process Management 1.4.1 Loading and Executing a Program 1.4.2 Loading an Overlay 1.5 File and Directory Management 1.5.1 Handles 1.5.2 File-Related Function Requests 1.5.3 Device-Related Function Requests 1.5.4 Directory-Related Function Requests 1.5.5 File Attributes 1.6 Microsoft Networks 1.7 National Language Support 1.8 Miscellaneous System-Management Functions 1.9 Old System Calls 1.9.1 File Control Block (FCB) 1.10 Using the System Calls 1.10.1 Issuing an Interrupt 1.10.2 Calling a Function Request 1.10.3 Using the Calls from a High-Level Language 1.10.4 Treatment of Registers 1.10.5 Handling Errors 1.10.6 System Call Descriptions 1.11 Interrupts 1.11.1 Conditions upon Entry 1.11.2 Requirements for an Interrupt 24H Handler 1.12 Function Requests Chapter 2 MS-DOS Device Drivers 2.1 Introduction 2.2 Format of a Device Driver 2.3 How to Create a Device Driver 2.3.1 Device Strategy Routine 2.3.2 Device Interrupt Routine 2.4 Installing Device Drivers 2.5 Device Headers 2.5.1 Pointer to Next Device Field 2.5.2 Attribute Field 2.5.3 Strategy and Interrupt Routines 2.5.4 Name Field 2.6 Request Header 2.6.1 Length of Record 2.6.2 Unit Code Field 2.6.3 Command Code Field 2.6.4 Status Field 2.7 Device Driver Functions 2.7.1 The Init Function 2.7.2 The Media Check Function 2.7.3 The Build BPB Function 2.7.4 The Read or Write Function 2.7.5 The Non-destructive Read, No Wait Function 2.7.6 The Open or Close Function 2.7.7 The Removable Media Function 2.7.8 The Status Function 2.7.9 The Flush Function 2.7.10 The Generic IOCtl Function 2.7.11 The Get/Set Logical Drive Map Function 2.8 The Media Descriptor Byte 2.9 Format of a Media Descriptor Table 2.10 The CLOCK Device 2.11 Anatomy of a Device Call 2.12 Two Sample Device Drivers Chapter 3 MS-DOS Technical Information 3.1 Introduction 3.2 MS-DOS Initialization 3.3 The Command Processor 3.4 MS-DOS Disk Allocation 3.5 MS-DOS Disk Directory 3.6 File Allocation Table (FAT) 3.6.1 How to Use the FAT (12-Bit FAT Entries) 3.6.2 How to Use the FAT (16-Bit FAT Entries) 3.7 MS-DOS Standard Disk Formats Chapter 4 MS-DOS Control Blocks and Work Areas 4.1 Introduction 4.2 Typical Contents of an MS-DOS Memory Map 4.3 The MS-DOS Program Segment Chapter 5 National Language Support 5.1 Introduction 5.2 National Language Support Calls 5.3 Font Files 5.3.1 Font File Structure Chapter 6 .Exe File Structure and Loading 6.1 Introduction 6.2 Format of a File Header 6.3 The Relocation Table Chapter 7 Relocatable Object Module Formats 7.1 Introduction 7.1.1 Definition of Terms 7.2 Module Identification and Attributes 7.2.1 Segment Definition 7.2.2 Addressing a Segment 7.2.3 Symbol Definition 7.2.4 Indices 7.3 Conceptual Framework for Fixups 7.3.1 Self-Relative Fixup 7.3.2 Segment-Relative Fixup 7.4 Record Sequence 7.5 Introducing the Record Formats 7.5.1 Sample Record Format (SAMREC) 7.5.2 T-Module Header Record (THEADR) 7.5.3 L-Module Header Record (LHEADR) 7.5.4 List of Names Record (LNAMES) 7.5.5 Segment Definition Record (SEGDEF) 7.5.6 Group Definition Record (GRPDEF) 7.5.7 Public Names Definition Record (PUBDEF) 7.5.8 Communal Names Definition Record (COMDEF) 7.5.9 Local Symbols Record (LOCSYM) 7.5.10 External Names Definition Record (EXTDEF) 7.5.11 Line Numbers Record (LINNUM) 7.5.12 Logical Enumerated Data Record (LEDATA) 7.5.13 Logical Iterated Data Record (LIDATA) 7.5.14 Fixup Record (FIXUPP) 7.5.15 Module End Record (MODEND) 7.5.16 Comment Record (COMENT) 7.6 Microsoft Type Representations for Communal Variables Chapter 8 Programming Hints 8.1 Introduction 8.2 Interrupts 8.3 System Calls 8.4 Device Management 8.5 Memory Management 8.6 Process Management 8.7 File and Directory Management 8.7.1 Locking Files 8.8 Miscellaneous Figures Figure 1.1 Example of the 8088 Registers Figure 1.2 Sample Program with Common Skeleton Figure 2.1 Sample Device Header Figure 2.2 Attribute Word for Character Devices Figure 2.3 Attribute Word for Block Devices Figure 2.4 Request Header Figure 2.5 Status Field Figure 2.6 Format of a Boot Sector Figure 2.7 Format of a Clock Device Figure 4.1 Program Segment Prefix Figure 5.1 Font File Structure Figure 7.1 Location Types Tables Table 1.1 Standard-Character I/O Function Requests Table 1.2 Memory Management Function Requests Table 1.3 Process-Management Function Requests Table 1.4 Predefined Device Handles Table 1.5 File-Related Function Requests Table 1.6 File-Sharing Function Requests Table 1.7 Device-Related Function Requests Table 1.8 Directory-Related Function Requests Table 1.9 File Attributes Table 1.10 Microsoft Networks Function Requests Table 1.11 National-Language-Support Function Requests Table 1.12 Miscellaneous System-Management Function Requests Table 1.13 Old System Calls and Their Replacements Table 1.14 Format of the File Control Block (FCB) Table 1.15 Error Codes Returned in AX Table 1.16 MS-DOS Interrupts, Numeric Order Table 1.17 MS-DOS Interrupts, Alphabetic Order Table 1.18 MS-DOS Function Requests, Numeric Order Table 1.19 MS-DOS Function Requests, Alphabetic Order Table 1.20 Bit Values for Function 29H Table 1.21 Sharing Mode Bit Values Table 1.22 Access Code Bit Values Table 1.23 MS-DOS Data Bit Values Table 1.24 Contents of the Parameter Block Table 1.25 Contents of the Parameter Block Table 1.26 DTA Values After Successful Find First File Table 1.27 Allocation Strategy Table 2.1 For Character Devices: Table 2.2 For Block Devices: Table 3.1 MS-DOS Standard Removable-Disk Formats Table 3.2 MS-DOS Standard Removable-Disk Formats (High-Density) Table 7.1 Object Module Record Formats Table 7.2 Combination Attribute Example ──────────────────────────────────────────────────────────────────────────── Chapter 1 System Calls 1.1 Introduction 1.1.1 System Calls That Have Been Superseded 1.1.2 How to Use This Manual 1.2 Standard Character Device I/O 1.3 Memory Management 1.4 Process Management 1.4.1 Loading and Executing a Program 1.4.2 Loading an Overlay 1.5 File and Directory Management 1.5.1 Handles 1.5.2 File-Related Function Requests 1.5.3 Device-Related Function Requests 1.5.4 Directory-Related Function Requests 1.5.5 File Attributes 1.6 Microsoft Networks 1.7 National Language Support 1.8 Miscellaneous System-Management Functions 1.9 Old System Calls 1.9.1 File Control Block (FCB) 1.10 Using the System Calls 1.10.1 Issuing an Interrupt 1.10.2 Calling a Function Request 1.10.3 Using the Calls from a High-Level Language 1.10.4 Treatment of Registers 1.10.5 Handling Errors 1.10.6 System Call Descriptions 1.11 Interrupts 1.11.1 Conditions upon Entry 1.11.2 Requirements for an Interrupt 24H Handler 1.12 Function Requests 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 likelihood that a program will be compatible with future versions of MS-DOS. MS-DOS system calls fall into several categories: ■ Standard character device I/O ■ Memory management ■ Process management ■ File and directory management ■ Microsoft Network calls ■ National Language Support calls ■ 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 earlier than 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) appear in Section 1.8, "Old System Calls." 1.1.2 How to Use This Manual The first part of this chapter explains how DOS manages its resources── such as memory, files, and processes──and 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. Chapter 2 of this manual describes how to write an MS-DOS device driver. Chapters 3 and 4 contain more detailed information about MS-DOS, including how it manages disk space, uses control blocks, and loads and executes relocatable programs (files with an extension of .exe). Chapter 5 describes MS-DOS national language support. Chapter 6 describes .exe file structure and loading procedures (for versions of MS-DOS earlier than 2.0). Chapter 7 describes the Intel object module format. Chapter 8 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-character input and output. Table 1.1 Standard-Character I/O Function Requests ╓┌─┌─────────┌─────────────────────┌─────────────────────────────────────────╖ Code Request Description ────────────────────────────────────────────────────────────────────────── 01H Read Keyboard and Gets a character from standard input and Echo 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 Code Request Description ────────────────────────────────────────────────────────────────────────── 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 Buffered Keyboard Gets a string from standard input Input 0BH Check Keyboard Reports on the status of the standard Status input buffer 0CH Flush Buffer, Read Empties the standard input buffer and Keyboard calls one of the other standard character Code Request Description ────────────────────────────────────────────────────────────────────────── Keyboard calls one of the other standard character ────────────────────────────────────────────────────────────────────────── 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 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 Code Request Description ────────────────────────────────────────────────────────────────────────── 48H Allocate Memory Requests a block of memory 49H Free Allocated Frees a block of memory previously Memory allocated with 48H 4AH Set Block Changes the size of an allocated memory ────────────────────────────────────────────────────────────────────────── 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 control 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. 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). 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 Code Request Description ────────────────────────────────────────────────────────────────────────── 31H Keep Process Terminates a process and returns control to the invoking process, but keeps the terminated process in memory 4B00H, Load and Execute Loads and executes a program, or loads a 4B03H Program or Overlay program overlay without executing it 4CH End Process Returns control to the invoking process 4DH Get Return Code of Returns a code passed by an exiting child Child Process process 62H Get PSP Returns the segment address of the current ────────────────────────────────────────────────────────────────────────── Function 4BH (Load and Execute Program or Overlay) has two subfunctions, 4B00H (Load and Execute Program) and 4B03H (Load Overlay). The differences between them are described in the following sections. 1.4.1 Loading and Executing a Program When a program uses Function 4B00H (Load and Execute Program) to load and execute another program, MS-DOS allocates memory, writes a Program Segment Prefix (PSP) for the new program at offset 0 of the allocated 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 4B00H 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──as a .com program is──or 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 possibility, a .com program should use Function 4AH (Set Block) to shrink its initial allocation block before doing anything else. Also, before exiting, all programs must release all memory they allocate by using Function 48H (Allocate Memory). Loading a .Exe Program When command.com loads and executes a .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. 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 executable 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 system 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. A handle can refer to either a file or a device. MS-DOS predefines five standard 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 information 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 structure 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 ╓┌─┌─────────┌─────────────────────┌─────────────────────────────────────────╖ Code Request Description ────────────────────────────────────────────────────────────────────────── 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 Creates a new handle that refers to the Code Request Description ────────────────────────────────────────────────────────────────────────── 45H Duplicate File Creates a new handle that refers to the Handle same file as an existing handle 46H Force Duplicate File Makes an existing handle refer to the same Handle file as another existing handle 5AH Create Temporary Creates a file with a unique name File 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 ────────────────────────────────────────────────────────────────────────── Code Request Description ────────────────────────────────────────────────────────────────────────── File Sharing Version 3.1 of MS-DOS introduced file sharing, which let 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 sharing 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. (Compatibility mode is usable without file sharing being in effect.) Table 1.6 File-Sharing Function Requests Code Request Description ────────────────────────────────────────────────────────────────────────── 3DH Open Handle Opens a file by using one of the file-sharing modes 440BH IOCtl Retry (before Interrupt 24H 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 function requests for managing devices. Table 1.7 Device-Related Function Requests ╓┌─┌──────────────┌─────────────────────────┌────────────────────────────────╖ Code Request Description ────────────────────────────────────────────────────────────────────────── 4400H, 4401H IOCtl Data Gets or sets device description 4402H, 4403H IOCtl Character Gets or sets character-device control data 4404H, 4405H IOCtl Block Gets or sets block-device control data 4406H, 4407H IOCtl Status Checks device input or output status 4408H IOCtl Is Changeable Checks whether block device contains removable medium 440CH Generic IOCtl (for Sets Generic IOCtl for handles handles) and supports code pages for Code Request Description ────────────────────────────────────────────────────────────────────────── handles) and supports code pages for devices or returns DCBS information. 440DH Generic IOCtl (for Sets Generic IOCtl for devices devices) 440EH, 440FH 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, extension, 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 ╓┌─┌─────────┌─────────────────────┌─────────────────────────────────────────╖ Code Request Description ────────────────────────────────────────────────────────────────────────── 39H Create Directory Creates a subdirectory 3AH Remove Directory Deletes a subdirectory Code Request Description ────────────────────────────────────────────────────────────────────────── 3AH Remove Directory Deletes a subdirectory 3BH Change Current Changes the current directory Directory 41H Delete Directory Deletes a file Entry (Unlink) 43H Get/Set File Retrieves or changes the attributes of a Attributes (Chmod) file 47H Get Current Returns current directory for a given Directory drive 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 Code Request Description ────────────────────────────────────────────────────────────────────────── that matches a filename 56H Change Directory Renames a file Entry 57H Get/Set Date/Time of Changes the time and date of last change File 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 ────────────────────────────────────────────────────────────────────────── 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 disk drives and devices have been redirected to the server. For a description of the operation and use of the network, see the Microsoft Networks Manager's Guide and Microsoft Networks User's Guide. Table 1.10 lists the MS-DOS function requests for managing a Microsoft Networks workstation. Table 1.10 Microsoft Networks Function Requests ╓┌─┌─────────┌─────────────────────┌─────────────────────────────────────────╖ Code Request Description ────────────────────────────────────────────────────────────────────────── 4409H IOCtl Is Redirected Checks whether a drive letter refers to a Block local or redirected drive Code Request Description ────────────────────────────────────────────────────────────────────────── Block local or redirected drive 440AH IOCtl Is Redirected Checks whether a device name refers to a Handle local or redirected device 5E00H Get Machine Name Gets the network name of the workstation 5E02H Set 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 Gets an entry from the assign list, which Entry shows the workstation drive letter or device name and the network name of the directory or device on the server to which the entry is reassigned 5F03H Make Network Redirects a workstation drive or device to Connection a server directory or device Code Request Description ────────────────────────────────────────────────────────────────────────── Connection a server directory or device 5F04H Delete Network Cancels the redirection of a workstation Connection drive or device to a server directory or ────────────────────────────────────────────────────────────────────────── 1.7 National Language Support National language support of MS-DOS includes these major features: ■ Country-dependent information ■ Support for national keyboard layouts ■ Programming interfaces for national language support ■ Utility commands Country-dependent information is available on a per-country basis and includes the following: ■ Time, date, and currency ■ Lowercase-to-uppercase character-conversion tables ■ Collating sequence for character sorting ■ Valid single-byte characters used in filenames Keyboard support for different keyboard layouts is provided and 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 Code Request Description ────────────────────────────────────────────────────────────────────────── 65H Get Extended Country Returns standard country information, Information pointer to uppercase table, pointer to filename uppercasing table, or pointer to collating table. 66H Get/Set Global Code Gets or sets the code page used by the Page kernel and all devices. ────────────────────────────────────────────────────────────────────────── 1.8 Miscellaneous System-Management Functions The remaining system calls manage other system functions and resources such as drives, addresses, and the clock. Table 1.12 lists the MS-DOS function requests for managing miscellaneous system resources and operations. Table 1.12 Miscellaneous System-Management Function Requests ╓┌─┌─────────┌─────────────────────┌─────────────────────────────────────────╖ Code Request Description ────────────────────────────────────────────────────────────────────────── 0DH Reset Disk Empties all file buffers 0EH Select Disk Sets the default drive 19H Get Current Disk Returns the default drive 1AH Set Disk Transfer Establishes the disk I/O buffer Address 1BH Get Default Drive Returns disk-format data 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 Code Request Description ────────────────────────────────────────────────────────────────────────── 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 Turns disk verify on or off Flag 2FH Get Disk Transfer Returns system-disk-I/O-buffer address Address 30H Get MS-DOS Version Returns MS-DOS version number Number 33H CONTROL+C Check Returns CONTROL+C check status Code Request Description ────────────────────────────────────────────────────────────────────────── 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 Old System Call Has Been Superseded By Code Function Code Function ────────────────────────────────────────────────────────────────────────── 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 4B00H, Load and Execute Program 4B03H or Overlay 27H Random Block Read 42H Move File Pointer 3FH Read Handle 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 31H Keep Process Resident Old System Call Has Been Superseded By Code Function Code Function ────────────────────────────────────────────────────────────────────────── Resident ────────────────────────────────────────────────────────────────────────── 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 ────────────────────────────────────────────────────────────────────────── 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 necessary) 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 necessary) 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 10H): 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 14H): The date the file was created or last updated. The year, month, and day are mapped into two bytes as follows: Offset 15H Offset 14H |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 16H): The time the file was created or last updated. The hour, minutes, and seconds are mapped into two bytes as follows: Offset 17H Offset 16H |H|H|H|H|H|M|M|M| |M|M|M|S|S|S|S|S| 15 11 10 5 4 0 Reserved (offset 18H): These fields are reserved for use by MS-DOS. Current Record (offset 20H): 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. Relative Record (offset 21H): Points to the currently selected record, counting 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 unformatted 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. ────────────────────────────────────────────────────────────────────────── 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 maintains the table of interrupt-handler addresses (the vector table) in locations 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: ■ Use the Interrupt 86 function of C to call a function request directly. ■ Use the DOSXQQ function of Pascal to call a function request directly. ■ Use the CALL statement or USER function to execute the required assembly-language code from the BASIC interpreter. 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 accommodate the interrupt system──at least 128 bytes in addition to other needs. 1.10.5 Handling Errors Most of the function requests introduced with MD-DOS 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 Code Meaning ────────────────────────────────────────────────────────────────────────── 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 30 Read Fault 31 General failure Code Meaning ────────────────────────────────────────────────────────────────────────── 31 General failure 32 Sharing violation 33 Lock violation 34 Wrong disk 35 FCB unavailable 36 Sharing buffer exceeded 37 Reserved 38 Handle end-of-file operation not completed 39-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 Code Meaning ────────────────────────────────────────────────────────────────────────── 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 Code Meaning ────────────────────────────────────────────────────────────────────────── 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 89 Function not supported by network 90 Required system component not installed ────────────────────────────────────────────────────────────────────────── 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 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 programs 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: ■ A diagram of the 8088 registers that shows their contents before and after the system call ■ A more complete description of the register contents required before the system call ■ A description of the processing performed ■ A more complete description of the register contents after the system call ■ 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. ┌───────┬───────┐ AX:│ AH │ AL │ ├───────┼───────┤ BX:│ BH │ BL │ ├───────┼───────┤ CX:│ CH │ CL │ ├───────┼───────┤ DX:│ DH │ DL │ └───────┴───────┘ ┌───────────────┐ │ SP │ ├───────────────┤ │ BP │ ├───────────────┤ │ SI │ ├───────────────┤ │ DI │ └───────────────┘ ┌───────────────┐ │ SP │ ├───────┬───────┤ │FLAGS H│FLAGS L│ └───────┴───────┘ ┌───────────────┐ │ CS │ ├───────────────┤ │ DS │ ├───────────────┤ │ SS │ ├───────────────┤ │ ES │ └───────────────┘ Figure 1.1 Example of the 8088 Registers 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 executed 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 programs. For instance, the sample program in the preceding figure includes four such macros: open_handle, read_handle, display, and end_process. 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 contain 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. 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 (performing 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 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 Function Description ────────────────────────────────────────────────────────────────────────── 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 Function Description ────────────────────────────────────────────────────────────────────────── 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 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 Function Description ────────────────────────────────────────────────────────────────────────── 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 Function Description ────────────────────────────────────────────────────────────────────────── 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 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 Function Description ────────────────────────────────────────────────────────────────────────── 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 4B00H, 4B03H Load and Execute Program or 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 Function Description ────────────────────────────────────────────────────────────────────────── 58H Get/Set Allocation Strategy 59H Get Extended Error 5AH Create Temporary File 5BH Create New File 5C00H, 5C01H Lock/Unlock Files 5DH Reserved 5E00H Get Machine Name 5E02H Set Printer Setup 5E03H Get Printer Setup 5F02H Get Assign-List Entry 5F03H Make Network Connection 5F04H Delete Network Connection 60H-61H Reserved 62H Get PSP 63H,64H Reserved 65H Get Extended Country Information 66H Get/Set Global Code Page 67H Set Handle Count 68H Commit File Function Description ────────────────────────────────────────────────────────────────────────── 68H Commit File 69H-6BH Reserved 6CH Extended Open/Create 6DH-7FH Reserved ────────────────────────────────────────────────────────────────────────── Table 1.19 MS-DOS Function Requests, Alphabetic Order ╓┌─┌───────────────────────────────────────────────────────┌─────────────────╖ Description Function ────────────────────────────────────────────────────────────────────────── Allocate Memory 48H Auxiliary Input 03H Auxiliary Output 04H Buffered Keyboard Input 0AH Change Current Directory 3BH Change Directory Entry 56H Check Keyboard Status 0BH Description Function ────────────────────────────────────────────────────────────────────────── 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 Delete Network Connection 5F04H Direct Console I/O 06H Direct Console Input 07H Display Character 02H Display String 09H Duplicate File Handle 45H Description Function ────────────────────────────────────────────────────────────────────────── Duplicate File Handle 45H End Process 4CH Extended Open/Create 6CH Find First File 4EH Find Next File 4FH Flush Buffer, Read Keyboard 0CH Force Duplicate File Handle 46H 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 Description Function ────────────────────────────────────────────────────────────────────────── 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 Printer Setup 5E03H 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 Description Function ────────────────────────────────────────────────────────────────────────── 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 4B00H Load Overlay 4B03H Lock/Unlock Files 5C00H, 5C01H Make Network Connection 5F03H Move File Pointer 42H Open File 0FH Open Handle 3DH Parse File Name 29H Print Character 05H Random Block Read 27H Random Block Write 28H Description Function ────────────────────────────────────────────────────────────────────────── 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-6BH Description Function ────────────────────────────────────────────────────────────────────────── Reserved 69H-6BH Reserved 6DH-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 Printer Setup 5E02H Set Relative Record 24H Set Time 2DH Set/Reset Verify Flag 2EH Terminate Program 00H Description Function ────────────────────────────────────────────────────────────────────────── Terminate Program 00H 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──both text and code──all numbers are in hexadecimal. ────────────────────────────────────────────────────────────────────────── 1.11 Interrupts The following pages describe Interrupts 20H-27H. ──────────────────────────────────────────────────────────────────────────── 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. ────────────────────────────────────────────────────────────────────────── 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 5C00H (Lock) for more information. ────────────────────────────────────────────────────────────────────────── Macro Definition: terminate macro int 20H endm Example: The following program displays a message and returns to MS-DOS. message db "displayed by INT20H example". 0DH, 0AH, "$" ; begin: display message ; see Function 09H terminate ; THIS INTERRUPT code ends end start ──────────────────────────────────────────────────────────────────────────── 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, "Function 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 ──────────────────────────────────────────────────────────────────────────── 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 Program Segment Prefix, starting at offset 0AH. ──────────────────────────────────────────────────────────────────────────── 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 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 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──including calling MS-DOS functions──as 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 or Overlay) 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 control to the calling program. ──────────────────────────────────────────────────────────────────────────── 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 Segment 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 routine. 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 routine handles these errors. This routine retries the disk operation, then gives you the choice of aborting the operation, retrying it, allowing the system call to fail and the application process to continue, or ignoring the error. The following topics describe the requirements of an Interrupt 24H routine, 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 control 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 program 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 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. However, 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 01H-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 the 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. 3 Fail the system call that is in progress. ────────────────────────────────────────────────────────────────────────── Notice 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 failing 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. 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 Error) to get detailed information about the error that caused the interrupt to be issued. ──────────────────────────────────────────────────────────────────────────── Absolute Disk Read (Interrupt 25H) ──────────────────────────────────────────────────────────────────────────── Call: AL Drive number DS:BX Disk Transfer Address or Far pointer to parameter packet if CX = -1 CX Number of sectors or -1 DX Beginning relative sector Return: AL Error code if CF=1 FLAGS CF = 0 if successful = 1 if not successful AX 0207 if attempt made to access partition larger than 32 megabytes with MS-DOS 3.3 or earlier. Comments: The registers must contain the following: Register Contents ────────────────────────────────────────────────────────────────────────── AL Drive number (0=A, 1=B, etc.) DS:BX Offset of Disk Transfer Address or far pointer to parameter packet if CX = -1 CX Number of sectors to read or -1 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. ────────────────────────────────────────────────────────────────────────── If CX = -1, DS:BX is the far pointer to the parameter packet. The parameter packet API provides access to partitions larger than 32 megabytes. The parameter packet contains: Starting sector number dd ? Number of sectors dw ? Transfer address dd ? 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 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 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 The following code is an example of reading the absolute sector with Interrupt 25H. mov al, 'C'-'A' ; select drive C: mov cx,-1 ; request new absolute format mov bx,code ; set ds:bx up to point to parameter mov ds,bx ; packet with sector number, length mov bx,offset par_pck ; and transfer address information int 25H ; do operation jc error_on_read ; check for errors par_pck: dd 12345H ; absolute sector number to read=12345H dw 2 ; number of sectors to read dd buffer ; transfer address buffer db 1024 dup (0) ; target buffer for read ──────────────────────────────────────────────────────────────────────────── Absolute Disk Write (Interrupt 26H) ──────────────────────────────────────────────────────────────────────────── Call: AL Drive number DS:BX Disk Transfer Address or Far pointer to parameter packet if CX = -1 CX Number of sectors or -1 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.) DS:BX Offset of Disk Transfer Address or far pointer to parameter packet if CX = -1 CX Number of sectors to write or -1 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 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. If CX = -1, DS:BX is the far pointer to the parameter packet. The parameter packet contains: Starting sector number dd ? Number of sectors dw ? Transfer address dd ? ────────────────────────────────────────────────────────────────────────── 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 32 kilobytes. 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 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 The following code is an example of writing the absolute sector with Interrupt 26H. mov al,'C'-'A' ; select drive C: mov cx,-1 ; request new absolute format mov bx,code ; set ds:bx up to point to parameter mov ds,bx ; packet with sector number, length mov bx,offset par_pck ; and transfer address information int 26H ; do operation jc error_on_write ; check for errors par_pck: dd 12345H ; absolute sector number to write=12345H dw 2 ; number of sectors to write dd buffer ; transfer address buffer db 1024 dup (0) ; target buffer for write ──────────────────────────────────────────────────────────────────────────── 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 interrupt 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 execution started). .Exe programs that are loaded into high memory must not use this interrupt. 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. 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. ──────────────────────────────────────────────────────────────────────────── Terminate Program (Function 00H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 00H CS Segment address of Program Segment Prefix Return: None Comments: Function 00H performs the same function as Interrupt 20H. It 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. The CS register must contain the segment address of the Program Segment Prefix before you call this interrupt. The following exit addresses are restored from the specified offsets in the Program Segment Prefix: Offset Exit Address ────────────────────────────────────────────────────────────────────────── 0AH Program terminate 0EH CONTROL+C 12H Critical error ────────────────────────────────────────────────────────────────────────── All file buffers are flushed to disk. ────────────────────────────────────────────────────────────────────────── Warning Close all files that have changed in length before calling this function. If you do not close a changed file, its length is not correctly recorded in the directory. See Function 10H for a description of the Close File system call. ────────────────────────────────────────────────────────────────────────── Macro Definition: terminate_program macro xor ah,ah int 21H 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 FUNC00H example", 0DH,0AH,"$" ; begin: display message ; see Function 09H terminate_program ; THIS FUNCTION code ends end start ──────────────────────────────────────────────────────────────────────────── Read Keyboard and Echo (Function 01H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 01H Return: AL Character typed Comments: Function 01H waits for a character to be read from standard input, then echoes the character to standard output and returns it in AL. If the character is CONTROL+C, it executes Interrupt 23H. Macro Definition: read_kbd_and_echo macro mov ah, 01H int 21H endm Example: The following program displays and prints characters as you type them. If you press the ENTER key, the program sends a linefeed/carriage-return sequence to both the display and the printer. begin: read_kbd_and_echo ; THIS FUNCTION print_char al ; see Function 05H cmp al,0DH ; is it a CR? jne begin ; no, print it print_char 0AH ; see Function 05H display_char 0AH ; see Function 02H jmp begin ; get another character ──────────────────────────────────────────────────────────────────────────── Display Character (Function 02H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 02H DL Character to be displayed Return: None Comments: Function 02H sends the character in DL to standard output. If you press CONTROL+C, it issues Interrupt 23H. Macro Definition: display_char macro character mov dl,character mov ah,02H int 21H endm Example: The following program converts lowercase characters to uppercase before displaying them. begin: read_kbd ; see Function 08H cmp al,"a" jl uppercase ; don't convert cmp al,"z" jg uppercase ; don't convert sub al,20H ; convert to ASCII code ; for uppercase uppercase: display_char al ; THIS FUNCTION jmp begin: ; get another character ──────────────────────────────────────────────────────────────────────────── Auxiliary Input (Function 03H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 03H Return: AL Character from auxiliary device Comments: Function 03H waits for a character from standard auxiliary devices (AUX, COM1, COM2, COM3, COM4), then returns the character in AL. This system call does not return a status or error code. If you press CONTROL+C, it issues Interrupt 23H. Macro Definition: aux_input macro mov ah,03H int 21H endm Example: The following program prints characters as soon as it receives them from the auxiliary device. It stops printing when it receives an end-of-file character (ASCII 26, or CONTROL+Z). begin: aux_input ; THIS FUNCTION cmp al,1AH ; end of file? je return ; yes, all done print_char al ; see Function 05H jmp begin ; get another character ──────────────────────────────────────────────────────────────────────────── Auxiliary Output (Function 04H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 04H DL Character for auxiliary device Return: None Comments: Function 04H sends the character in DL to standard auxiliary. This system call does not return a status or error code. If you press CONTROL+C, it issues Interrupt 23H. Macro Definition: aux_output macro character mov dl,character mov ah,04H int 21H endm Example: The following program gets a series of strings of up to 80 bytes from the keyboard and sends each string to the auxiliary device. It stops when you type a null string (carriage-return only). string db 81 dup(?) ; see Function 0AH ; begin: get_string 80,string ; see Function 0AH cmp string[1],0 ; null string? je return ; yes, all done mov cx, word ptr string[1] ; get string length mov bx,0 ; set index to 0 send_it: aux_output string[bx+2] ; THIS FUNCTION inc bx ; bump index loop send_it ; send another character jmp begin ; get another string ──────────────────────────────────────────────────────────────────────────── Print Character (Function 05H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 05H DL Character for printer Return: None Comments: Function 05H sends the character in DL to the standard printer. If you press CONTROL+C, it issues Interrupt 23H. This function does not return a status or error code. Macro Definition: print_char macro character mov dl,character mov ah,05H int 21H endm Example: The following program prints a walking test pattern on the printer. It stops if you press CONTROL+C. line_num db 0 ; begin: mov cx,60 ; print 60 lines start_line: mov bl,33 ; first printable ASCII ; character (!) add bl,line_num ; to offset one character push cx ; save number-of-lines counter mov cx,80 ; loop counter for line print_it: print_char bl ; THIS FUNCTION inc bl ; move to next ASCII character cmp bl,126 ; last printable ASCII ; character (~) jl no_reset ; not there yet mov bl,33 ; start over with (!) no_reset: loop print_it ; print another character print_char 0DH ; carriage return print_char 0AH ; linefeed inc line_num ; to offset 1st char. of line pop cx ; restore #-of-lines counter loop start_line ; print another line ──────────────────────────────────────────────────────────────────────────── Direct Console I/O (Function 06H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 06H DL See text Return: AL If DL = FFH before call, then zero flag not set means AL has character from standard input. Zero flag set means there was not a character to get, and AL = 0. Comments: The action of Function 06H depends on the value in DL when the function is called: Value in DL Action ────────────────────────────────────────────────────────────────────────── FFH If a character has been read from standard input, it is returned in AL and the zero flag is cleared (0); if a character has not been read, the zero flag is set (1). Not FFH The character in DL is sent to standard output. ────────────────────────────────────────────────────────────────────────── This function does not check for CONTROL+C. Macro Definition: dir_console_io macro switch mov dl,switch mov ah,06H int 21H endm Example: The following program sets the system clock to 0 and displays the time continuously. When you type any character, the display freezes; when you type any character again, the clock is reset to 0 and the display starts again. time db "00:00:00.00",0DH,0AH,"$" ; see Function 09H ; ; for explanation of $ ; begin: set_time 0,0,0,0 ; see Function 2DH read_clock: get_time ; see Function 2CH CONVERT ch,time ; see end of chapter CONVERT cl,time[3] ; see end of chapter CONVERT dh,time[6] ; see end of chapter CONVERT dl,time[9] ; see end of chapter display time ; see Function 09H dir_console_io FFH ; THIS FUNCTION cmp al,0 ; character typed? jne stop ; yes, stop timer jmp read_clock ; no, keep timer ; running stop: read_kbd ; see Function 08H jmp begin ; start over ──────────────────────────────────────────────────────────────────────────── Direct Console Input (Function 07H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 07H Return: AL Character from keyboard Comments: Function 07H waits for a character to be read from standard input, then returns it in AL. This function does not echo the character or check for CONTROL+C. (For a keyboard input function that echoes or checks for CONTROL+C, see Function 01H or 08H.) Macro Definition: dir_console_input macro mov ah,07H int 21H endm Example: The following program prompts for a password (eight characters maximum) and places the characters into a string without echoing them. password db 8 dup(?) prompt db "Password: $" ; see Function 09H for ; explanation of $ begin: display prompt ; see Function 09H mov cx,8 ; maximum length of password xor bx,bx ; so BL can be used as index get_pass: dir_console_input ; THIS FUNCTION cmp al,0DH ; was it a carriage return? je return ; yes, all done mov password[bx],al ; no, put character in string inc bx ; bump index loop get_pass ; get another character ──────────────────────────────────────────────────────────────────────────── Read Keyboard (Function 08H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 08H Return: AL Character from keyboard Comments: Function 08H waits for a character to be read from standard input, then returns it in AL. If you press CONTROL+C, it issues Interrupt 23H. This function does not echo the character. (For a keyboard input function that echoes the character or checks for CONTROL+C, see Function 01H.) Macro Definition: read_kbd macro mov ah,08H int 21H endm Example: The following program prompts for a password (eight characters maximum) and places the characters into a string without echoing them. password db 8 dup(?) prompt db "Password: $" ; see Function 09H ; for explanation of $ begin: display prompt ; see Function 09H mov cx,8 ; maximum length of password xor bx,bx ; BL can be an index get_pass: read_kbd ; THIS FUNCTION cmp al,0DH ; was it a carriage return? je return ; yes, all done mov password[bx],al ; no, put char. in string inc bx ; bump index loop get_pass ; get another character ──────────────────────────────────────────────────────────────────────────── Display String (Function 09H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 09H DS:DX Pointer to string to be displayed Return: None Comments: Function 09H sends to standard output a string that ends with "$" (the $ is not displayed). The DX register must contain the offset (from the segment address in DS) of the string. Macro Definition: display macro string mov dx,offset string mov ah,09H int 21H endm Example: The following program displays the hexadecimal code of the key that is typed. table db "0123456789ABCDEF" result db " - 00H",0DH,0AH,"$" ; see text for ; explanation of $ begin: read_kbd_and_echo ; see Function 01H xor ah,ah ; clear upper byte convert ax,16,result[3] ; see end of chapter display result ; THIS FUNCTION jmp begin ; do it again ──────────────────────────────────────────────────────────────────────────── Buffered Keyboard Input (Function 0AH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 0AH DS:DX Pointer to input buffer Return: None Comments: Function 0AH gets a string from standard input. DX must contain the offset (from the segment address in DS) of an input buffer of the following form: Byte Contents ────────────────────────────────────────────────────────────────────────── 1 Maximum number of characters in buffer, including the carriage return (you must set this value). 2 Actual number of characters typed, not counting the carriage return (the function sets this value). 3-n Buffer; must be at least as long as the number in byte ────────────────────────────────────────────────────────────────────────── Characters are read from standard input and placed in the buffer beginning at the third byte until an ENTER character (ASCII 0DH) is read. If the buffer fills to one less than the maximum, additional characters read are ignored and ASCII 07H (Bel) is sent to standard output until an ENTER character is read. If you type the string at the console, it can be edited as it is being entered. If you press CONTROL+C, it issues Interrupt 23H. MS-DOS sets the second byte of the buffer to the number of characters read (not counting the carriage return). Macro Definition: get_string macro limit,string mov dx,offset string mov string,limit mov ah,0AH int 21H endm Example: The following program gets a 16-byte (maximum) string from the keyboard and fills a 24-line by 80-character screen with it. buffer label byte max_length db ? ; maximum length chars_entered db ? ; number of chars. string db 17 dup (?) ; 16 chars + CR strings_per_line dw 0 ; how many strings ; fit on line crlf db 0DH,0AH ; begin: get_string 17,buffer ; THIS FUNCTION xor bx,bx ; so byte can be ; used as index mov bl,chars_entered ; get string length mov buffer[bx+2],"$" ; see Function 09H mov al,50H ; columns per line cbw div chars_entered ; times string fits ; on line xor ah,ah ; clear remainder mov strings_per_line,ax ; save col. counter mov cx,24 ; row counter display_screen: push cx ; save it mov cx,strings_per_line ; get col. counter display_line: display string ; see Function 09H loop display_line display crlf ; see Function 09H pop cx ; get line counter loop display_screen ; display 1 more line ──────────────────────────────────────────────────────────────────────────── Check Keyboard Status (Function 0BH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 0BH Return: AL 00H = no characters in type-ahead buffer FFH = characters in type-ahead buffer Comments: Function 0BH checks whether characters are available from standard input (if standard input has not been redirected, it checks the type-ahead buffer). If characters are available, AL returns FFH; if not, AL returns 0. If CONTROL+C is in the buffer, it issues Interrupt 23H. Macro Definition: check_kbd_status macro mov ah,0BH int 21H endm Example: The following program displays the time continuously until you press any key: time db "00:00:00.00",0DH,0AH,"$" . . begin: get_time ; see Function 2CH byte_to_dec ch,time ; see end of chapter byte_to_dec cl,time[3] ; see end of chapter byte_to_dec dh,time[6] ; see end of chapter byte_to_dec dl,time[9] ; see end of chapter display time ; see Function 09H check_kbd_status ; THIS FUNCTION cmp al,0FFH ; has a key been typed? je return ; yes, go home jmp begin ; no, keep displaying ; time ──────────────────────────────────────────────────────────────────────────── Flush Buffer, Read Keyboard (Function 0CH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 0CH AL 1, 6, 7, 8, or 0AH = the corresponding function is called. Any other value = no further processing. Return: AL 00H = Type-ahead buffer was flushed; no other processing performed. Comments: Function 0CH empties the standard input buffer (if standard input has not been redirected, Function 0CH empties the type-ahead buffer). Further processing depends on the value in AL when the function is called. AL Action ────────────────────────────────────────────────────────────────────────── 1,6,7,8, or 0AH The corresponding MS-DOS function is executed. Any other value No further processing; AL returns 0. ────────────────────────────────────────────────────────────────────────── Macro Definition: flush_and_read_kbd macro switch mov al,switch mov ah,0CH int 21H endm Example: The following program both displays and prints characters as you type them. If you press the ENTER key, the program sends a carriage-return/linefeed sequence to both the display and the printer. begin: flush_and_read_kbd 1 ; THIS FUNCTION print_char al ; see Function 05H cmp al,0DH ; is it a carriage return? jne begin ; no, print it print_char 0AH ; see Function 05H display_char 0AH ; see Function 02H jmp begin ; get another character ──────────────────────────────────────────────────────────────────────────── Reset Disk (Function 0DH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 0DH Return: None Comments: Function 0DH flushes all file buffers to ensure that the internal buffer cache matches the disks in the drives. It writes out buffers that have been modified and marks all buffers in the internal cache as free. This function request is normally used to force a known state of the system; CONTROL+C interrupt handlers should call this function. This function does not update directory entries; you must close changed files to update their directory entries (see Function 10H, Close File). Macro Definition: reset_disk macro mov ah,0DH int 21H endm Example: The following program flushes all file buffers and selects disk A. begin: reset_disk select_disk "A" ──────────────────────────────────────────────────────────────────────────── Select Disk (Function 0EH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 0EH DL Logical drive number (0 = A, 1 = B, etc.) Return: AL Number of logical drives Comments: Function 0EH selects the drive specified in DL (0=A, 1=B, etc.) as the current logical drive. AL returns the number of logical drives. ────────────────────────────────────────────────────────────────────────── Note For future compatibility, treat the value returned in AL with care. For example, if AL returns 5, it is not safe to assume that drives A, B, C, D, and E are all valid drive designators. ────────────────────────────────────────────────────────────────────────── Macro Definition: select_disk macro disk mov dl,disk[-64] mov ah,0EH int 21H endm Example: The following program toggles between drive A and drive B to select the current drive (in a two-drive system). begin: current_disk ; see Function 19H cmp al,00H ; drive A: selected? je select_b ; yes, select B select_disk "A" ; THIS FUNCTION jmp return select_b: select_disk "B" ; THIS FUNCTION ──────────────────────────────────────────────────────────────────────────── Open File (Function 0FH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 0FH DS:DX Pointer to unopened FCB Return: AL 00H = Directory entry found FFH = No directory entry found Comments: Function 0FH opens a file. DX must contain the offset (from the segment address in DS) of an unopened File Control Block (FCB). This call searches the disk directory for the named file. If the call finds a directory entry for the file, AL returns 0 and the FCB is filled as follows: ■ If the drive code was 0 (current drive), it is changed to the actual drive used (1=A, 2=B, etc.). This lets you change the current drive without interfering with subsequent operations on this file. ■ Current Block (offset 0CH) is set to 0. ■ Record Size (offset 0EH) is set to the system default of 128. ■ File Size (offset 10FH), Date of Last Write (offset 14H), and Time of Last Write (offset 16H) are set from the directory entry. Before performing a sequential disk operation on the file, you must set the Current Record field (offset 20H). Before performing a random disk operation on the file, you must set the Relative Record field (offset 21H). If the default record size (128 bytes) is not correct, set it to the correct length. If the call doesn't find a directory entry for the file, or if the file has the hidden or system attribute, AL returns FFH. Macro Definition: open macro fcb mov dx,offset fcb mov ah,0FH int 21H endm Example: The following program prints a file named textfile.asc that is on the disk in drive B. If a partial record is in the buffer at end-of-file, the routine that prints the partial record prints characters until it encounters an end-of-file mark (ASCII 26, or CONTROL+Z). fcb db 2,"TEXTFILEASC" db 26 dup (?) buffer db 128 dup (?) ; begin: set_dta buffer ; see Function 1AH open fcb ; THIS FUNCTION read_line: read_seq fcb ; see Function 14H cmp al,02H ; end of file? je all_done ; yes, go home cmp al,00H ; more to come? jg check_more ; no, check for partial ; record mov cx,80H ; yes, print the buffer xor si,si ; set index to 0 print_it: print_char buffer[si] ; see Function 05H inc si ; bump index loop print_it ; print next character jmp read_line ; read another record check_more: cmp al,03H ; part. record to print? jne all_done ; no mov cx,80H ; yes, print it xor si,si ; set index to 0 find_eof: cmp buffer[si],26 ; end-of-file mark? je all_done ; yes print_char buffer[si] ; see Function 05H inc si ; bump index to next ; character loop find_eof all_done: close fcb ; see Function 10H ──────────────────────────────────────────────────────────────────────────── Close File (Function 10H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 10H DS:DX Pointer to opened FCB Return: AL 00H = Directory entry found FFH = No directory entry found Comments: Function 10H closes a file. DX must contain the offset (to the segment address in DS) of an opened FCB. This call searches the disk directory for the file named in the FCB. If it finds a directory entry for the file, it compares the location of the file with the corresponding entries in the FCB. The call then updates the directory entry, if necessary, to match the FCB, and AL returns 0. After you change a file, you must call this function to update the directory entry. You should close any FCB (even one for a file that has not been changed) when you no longer need access to a file. If this call doesn't find a directory entry for the file, AL returns FFH. Macro Definition: close macro fcb mov dx,offset fcb mov ah,10H int 21H endm Example: The following program checks the first byte of the file named mod1.bas in drive B to see if it is FFH and, if it is, prints a message. message db "Not saved in ASCII format",0DH,0AH,"$" fcb db 2,"MOD1 BAS" db 26 dup (?) buffer db 128 dup (?) ; begin: set_dta buffer ; see Function 1AH open fcb ; see Function 0FH read_seq fcb ; see Function 14H cmp buffer,0FFH ; is first byte FFH? jne all_done ; no display message ; see Function 09H all_done: close fcb ; THIS FUNCTION ──────────────────────────────────────────────────────────────────────────── Search for First Entry (Function 11H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 11H DS:DX Pointer to unopened FCB Return: AL 00H = Directory entry found FFH = No directory entry found Comments: Function 11H searches the disk directory for the first matching filename. DX must contain the offset (from the segment address in DS) of an unopened FCB. The filename in the FCB can include wildcard characters. To search for hidden or system files, DX must point to the first byte of an extended FCB prefix. If this call does not find a directory entry for the filename in the FCB, AL returns FFH. But if the call does find a directory entry for the filename in the FCB, AL returns 0 and the call creates an unopened FCB of the same type (normal or extended) at the Disk Transfer Address as follows: 1. If the search FCB was normal, the first byte at the Disk Transfer Address is set to the drive number used in the search (1=A, 2=B, etc.) and the next 32 bytes contain the directory entry. 2. If the search FCB was extended, the first byte at the Disk Transfer Address is set to FFH, the next 5 bytes are set to 00H, and the following byte is set to the value of the attribute byte in the search FCB. The remaining 33 bytes are the same as the result of the normal FCB (drive number and 32 bytes of directory entry). If you use Function 12H (Search for Next Entry) to continue searching for matching filenames, you must not alter or open the original FCB at DS:DX. The attribute field is the last byte of the extended FCB fields that precede the FCB (see Extended FCB in Section 1.9.1). If the attribute field is zero, Function 11H searches only normal file entries. It does not search directory entries for hidden files, system files, volume label, and subdirectories. If the attribute field is hidden file, system file, or subdirectory entry (02H, 04H, or 10H), or any combination of those values, this call also searches all normal file entries. To search all directory entries except the volume label, set the attribute byte to 16H (hidden file and system file and subdirectory entry). If the attribute field is Volume ID (08H), the call searches only the volume label entry. Macro Definition: search_first macro fcb mov dx,offset fcb mov ah,11H int 21H endm Example: The following program verifies the existence of a file named report.asm on the disk in drive B. yes db "FILE EXISTS.$" no db "FILE DOES NOT EXIST.$" crlf db 0DH,0AH,"$" fcb db 2,"REPORT *ASM" db 26 dup (?) buffer db 128 dup (?) ; begin: set_dta buffer ; see Function 1AH search_first fcb ; THIS FUNCTION cmp al,0FFH ; directory entry found? je not_there ; no display yes ; see Function 09H jmp continue not_there: display no ; see Function 09H continue: display crlf ; see Function 09H ──────────────────────────────────────────────────────────────────────────── Search for Next Entry (Function 12H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 12H DS:DX Pointer to unopened FCB Return: AL 00H = Directory entry found FFH = No directory entry found Comments: After you use Function 11H (Search for First Entry), you can use Function 12H to find any additional directory entries that match a filename (containing wildcard characters). Function 12H searches the disk directory for the next matching name. DX must contain the offset (from the segment address in DS) of an FCB specified in a previous call to Function 11H. To search for hidden or system files, DX must point to the first byte of an extended FCB prefix──one that includes the appropriate attribute value. If the call does not find a directory entry for the filename in the FCB, AL returns FFH. But if the call does find a directory entry for the filename in the FCB, AL returns 0 and the call creates an unopened FCB of the same type (normal or extended) at the Disk Transfer Address (see Function 11H for a description of how the unopened FCB is formed). Macro Definition: search_next macro fcb mov dx,offset fcb mov ah,12H int 21H endm Example: The following program displays the number of files on the disk in drive B. message db "No files",0DH,0AH,"$" files db 0 fcb db 2,"???????????" db 26 dup (?) buffer db 128 dup (?) ; begin: set_dta buffer ; see Function 1AH search_first fcb ; see Function 11H cmp al,0FFH ; directory entry found? je all_done ; no, no files on disk inc files ; yes, increment file ; counter search_dir: search_next fcb ; THIS FUNCTION cmp al,0FFH ; directory entry found? je done ; no inc files ; yes, increment file ; counter jmp search_dir ; check again done: convert files,10,message ; see end of chapter all_done: display message ; see Function 09H ──────────────────────────────────────────────────────────────────────────── Delete File (Function 13H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 13H DS:DX Pointer to unopened FCB Return: AL 00H = Directory entry found FFH = No directory entry found Comments: Function 13H deletes a file. DX must contain the offset (from the segment address in DS) of an unopened FCB. This call searches the directory for a matching filename. The filename in the FCB can contain wildcard characters. If the call does not find a matching directory entry, AL returns FFH. But if the call does find a matching directory entry, AL returns 0 and the call deletes the entry from the directory. If the filename contains a wildcard character, the call will delete all files that match. Do not delete open files. Macro Definition: delete macro fcb mov dx,offset fcb mov ah,13H int 21H endm Example: The following program deletes each file on the disk in drive B that was last written before December 31, 1982. year dw 1982 month db 12 day db 31 files db 0 message db "No files deleted.",0DH,0AH,"$" fcb db 2,"???????????" db 26 dup (?) buffer db 128 dup (?) ; begin: set_dta buffer ; see Function 1AH search_first fcb ; see Function 11H cmp al,0FFH ; directory entry found? jne compare ; yes jmp all_done ; no, no files on disk compare: convert_date buffer ; see end of chapter cmp cx,year ; next several lines jg next ; check date in directory cmp dl,month ; entry against date jg next ; above & check next file cmp dh,day ; if date in directory jge next ; entry isn't earlier. delete buffer ; THIS FUNCTION inc files ; bump deleted-files ; counter next: search_next fcb ; see Function 12H cmp al,00H ; directory entry found? je compare ; yes, check date cmp files,0 ; any files deleted? je all_done ; no, display No files ; message. convert files,10,message ; see end of chapter all_done: display message ; see Function 09H ──────────────────────────────────────────────────────────────────────────── Sequential Read (Function 14H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 14H DS:DX Pointer to opened FCB Return: AL 00H = Read completed successfully 01H = EOF 02H = DTA too small 03H = EOF, partial record Comments: Function 14H reads a record from a specified file. DX must contain the offset (from the segment address in DS) of an opened FCB. This call loads the record pointed to by the Current Block field (offset 0CH) and Current Record (offset 20H) field at the Disk Transfer Address, then increments the Current Block and Current Record fields. The length of the record is taken from the Record Size field (offset 0EH) of the FCB. AL returns a code that describes the processing: Code Meaning ────────────────────────────────────────────────────────────────────────── 0 Read completed successfully 1 End-of-file; no data in the record 2 Not enough room at the Disk Transfer Address to read one record; read canceled 3 End-of-file; a partial record was read and padded to ────────────────────────────────────────────────────────────────────────── Macro Definition: read_seq macro fcb mov dx,offset fcb mov ah,14H int 21H endm Example: The following program displays a file named textfile.asc that is on the disk in drive B; its function is similar to the MS-DOS type command. If a partial record is in the buffer at end-of-file, the routine that displays the partial record displays characters until it encounters an end-of-file mark (ASCII 26, or CONTROL+Z). fcb db 2,"TEXTFILEASC" db 26 dup (?) buffer db 128 dup (?),"$" ; begin: set_dta buffer ; see Function 1AH open fcb ; see Function 0FH read_line: read_seq fcb ; THIS FUNCTION cmp al,02H ; DTA too small? je all_done ; yes cmp al,00H ; end-of-file? jg check_more ; yes display buffer ; see Function 09H jmp read_line ; get another record check_more: cmp al,03H ; partial record in buffer? jne all_done ; no, go home xor si,si ; set index to 0 find_eof: cmp buffer[si],26 ; is character EOF? je all_done ; yes, no more to display display_char buffer[si] ; see Function 02H inc si ; bump index jmp find_eof ; check next character all_done: close fcb ; see Function 10H ──────────────────────────────────────────────────────────────────────────── Sequential Write (Function 15H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 15H DS:DX Pointer to opened FCB Return: AL 00H = Write completed successfully 01H = Disk full 02H = DTA too small Comments: Function 15H writes a record to a specified file. DX must contain the offset (from the segment address in DS) of an opened FCB. This call writes the record pointed to by the Current Block field (offset 0CH) and Current Record field (offset 20H) at the Disk Transfer Address, then increments the Current Block and Current Record fields. The record size is taken from the value of the Record Size field (offset 0EH) of the FCB. If the record size is less than a sector, the call writes the data at the Disk Transfer Address to an MS-DOS buffer; MS-DOS writes the buffer to disk when it contains a full sector of data, when the file is closed, or when Function 0DH (Reset Disk) is issued. AL returns a code that describes the processing: Code Meaning ────────────────────────────────────────────────────────────────────────── 0 Write completed successfully 1 Disk full; write canceled 2 Not enough room at the Disk Transfer Address to write ────────────────────────────────────────────────────────────────────────── Macro Definition: write_seq macro fcb mov dx,offset fcb mov ah,15H int 21H endm Example: The following program creates a file named dir.tmp on the disk in drive B containing the disk number (0=A, 1=B, etc.) and filename from each directory entry on the disk. record_size equ 0EH ; offset of Record Size ; field in FCB fcb1 db 2,"DIR TMP" db 26 dup (?) fcb2 db 2,"???????????" db 26 dup (?) buffer db 128 dup (?) ; begin: set_dta buffer ; see Function 1AH search_first fcb2 ; see Function 11H cmp al,0FFH ; directory entry found? je all_done ; no, no files on disk create fcb1 ; see Function 16H mov fcb1[record_size],12 ; set record size to 12 write_it: write_seq fcb1 ; THIS FUNCTION cmp al,0 ; write successful? jne all_done ; no, go home search_next fcb2 ; see Function 12H cmp al,FFH ; directory entry found? je all_done ; no, go home jmp write_it ; yes, write the record all_done: close fcb1 ; see Function 10H ──────────────────────────────────────────────────────────────────────────── Create File (Function 16H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 16H DS:DX Pointer to unopened FCB Return: AL 00H = Empty directory found FFH = No empty directory available Comments: Function 16H creates a file. DX must contain the offset (from the segment address in DS) of an unopened FCB. MS-DOS searches the directory for an entry that matches the specified filename or, if there is no matching entry, an empty entry. If MS-DOS finds a matching entry, it opens the file and sets the length to zero (in other words, if you try to create a file that already exists, MS-DOS erases it and creates a new, empty file). If MS-DOS doesn't find a matching entry but does find an empty directory entry, it opens the file and sets its length to zero. In either case, the call creates the file, and AL returns 0. If MS-DOS doesn't find a matching entry and there is no empty entry, the call doesn't create the file, and AL returns FFH. You can assign an attribute to the file by using an extended FCB with the attribute byte set to the appropriate value (see "Extended FCB" in Section 1.9.1). Macro Definition: create macro fcb mov dx,offset fcb mov ah,16H int 21H endm Example: The following program creates a file named dir.tmp on the disk in drive B containing the disk number (0 = A, 1 = B, etc.) and filename from each directory entry on the disk. record_size equ 0EH ; offset of Record Size ; field of FCB fcb1 db 2,"DIR TMP" db 26 dup (?) fcb2 db 2,"???????????" db 26 dup (?) buffer db 128 dup (?) ; begin: set_dta buffer ; see Function 1AH search_first fcb2 ; see Function 11H cmp al,0FFH ; directory entry found? je all_done ; no, no files on disk create fcb1 ; THIS FUNCTION mov fcb1[record_size],12 ; set record size to 12 write_it: write_seq fcb1 ; see Function 15H cmp al,0 ; write successful jne all_done ; no, go home search_next fcb2 ; see Function 12H cmp al,FFH ; directory entry found? je all_done ; no, go home jmp write_it ; yes, write the record all_done: close fcb1 ; see Function 10H ──────────────────────────────────────────────────────────────────────────── Rename File (Function 17H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 17H DS:DX Pointer to modified FCB in the following nonstandard format: Byte(s) Contents ─────────────────────────────────────────────────────────────────────── 00H Drive number 01H-08H Old filename (padded with blanks, if necessary) 09H-0BH Old file extension (padded with blanks, if necessary) 0CH-10H Zeroed out 11H-18H New filename (padded with blanks, if necessary) 19H-1BH New file extension (padded with blanks, if necessary) 11CH-24H Zeroed out ─────────────────────────────────────────────────────────────────────── Return: AL 00H = Directory entry found FFH = No directory entry found or destination already exists Comments: Function 17H changes the name of an existing file. DX must contain the offset (from the segment address in DS) of an FCB with the drive number and filename filled in, followed by a second filename at offset 11H. DOS searches the disk directory for an entry that matches the first filename. This filename can contain wildcard characters. If MS-DOS finds a matching directory entry and there is no directory entry that matches the second filename, it changes the filename in the directory entry to match the second filename in the modified FCB. AL then returns zero. If the second filename does contain a wildcard character, this call does not change the corresponding characters in the filename of the directory entry. You cannot use this function request to rename a hidden file, a system file, or a subdirectory. If MS-DOS does not find a matching directory entry or if it finds an entry for the second filename, AL returns FFH. Macro Definition: rename macro fcb,newname mov dx,offset fcb mov ah,17H int 21H endm Example: The following program prompts for the name of a file and a new name; it then renames the file. fcb db 37 dup (?) prompt1 db "Filename: $" prompt2 db "New name: $" reply db 15 dup(?) crlf db 0DH,0AH,"$" ; begin: display prompt1 ; see Function 09H get_string 15,reply ; see Function 0AH display crlf ; see Function 09H parse reply[2],fcb ; see Function 29H display prompt2 ; see Function 09H get_string 15,reply ; see Function 0AH display crlf ; see Function 09H parse reply[2],fcb[16] ; see Function 29H rename fcb ; THIS FUNCTION ──────────────────────────────────────────────────────────────────────────── Get Current Disk (Function 19H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 19H Return: AL Currently selected drive (0 = A, 1 = B, etc.) Comments: Function 19H returns the current drive in AL (0=A, 1=B, etc.). Macro Definition: current_disk macro mov ah,19H int 21H endm Example: The following program displays the default drive in a two-drive system. message db "Current disk is $" crlf db 0DH,OAH,"$" ; begin: display message ; see Function 09H current_disk ; THIS FUNCTION cmp al,00H ; is it disk A? jne disk_b ; no, it's disk B: display_char "A" ; see Function 02H jmp all_done disk_b: display_char "B" ; see Function 02H all_done: display crlf ; see Function 09H ──────────────────────────────────────────────────────────────────────────── Set Disk Transfer Address (Function 1AH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 1AH DS:DX Disk Transfer Address Return: None Comments: Function 1AH sets the Disk Transfer Address. DX must contain the offset (from the segment address in DS) of the Disk Transfer Address. Disk transfers cannot wrap around from the end of the segment to the beginning, nor can they overflow into another segment. If you do not set the Disk Transfer Address, MS-DOS defaults to offset 80H in the Program Segment Prefix. You can check the current Disk Transfer Address with Function 2FH (Get Disk Transfer Address). Macro Definition: set_dta macro buffer mov dx,offset buffer mov ah,1AH int 21H endm Example: The following program prompts for a letter, converts it to its alphabetic sequence (A=1, B=2, etc.), then reads and displays the corresponding record from a file named alphabet.dat that is on the disk in drive B. The file contains 26 records, each 28 bytes long. record_size equ 0EH ; offset of Record Size ; field of FCB relative_record equ 21H ; offset of Relative Record ; field of FCB fcb db 2,"ALPHABETDAT" db 26 dup (?) buffer db 28 dup(?),"$" prompt db "Enter letter: $" crlf db 0DH,0AH,"$" ; begin: set_dta buffer ; THIS FUNCTION open fcb ; see Function 0FH mov fcb[record_size],28 ; set record size get_char: display prompt ; see Function 09H read_kbd_and_echo ; see Function 01H cmp al,0DH ; just a CR? je all_done ; yes, go home sub al,41H ; convert ASCII ; code to record # mov fcb[relative_record],al ; set relative record display crlf ; see Function 09H read_ran fcb ; see Function 21H display buffer ; see Function 09H display crlf ; see Function 09H jmp get_char ; get another character all_done: close fcb ; see Function 10H ──────────────────────────────────────────────────────────────────────────── Get Default Drive Data (Function 1BH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 1BH Return: AL Sectors per cluster CX Bytes per sector DX Clusters per drive DS:BX Pointer to FAT ID byte Comments: Function 1BH retrieves data about the disk in the default drive. The data returns in the following registers: Register Contents ────────────────────────────────────────────────────────────────────────── AL Number of sectors in a cluster (allocation unit) CX Number of bytes in a sector DX Number of clusters on the disk ────────────────────────────────────────────────────────────────────────── BX returns the offset (to the segment address in DS) of the first byte of the File Allocation Table (FAT), which identifies the type of disk in the drive: Value Type of Drive ────────────────────────────────────────────────────────────────────────── FF Double-sided disk, 8 sectors per track, 40 tracks per side FE Single-sided disk, 8 sectors per track, 40 tracks per side FD Double-sided disk, 9 sectors per track, 40 tracks per side FC Single-sided disk, 9 sectors per track, 40 tracks per side F9 Double-sided disk, 15 sectors per track, 40 tracks per side F9 Double-sided disk, 9 sectors per track, 80 tracks per side F8 Fixed disk ────────────────────────────────────────────────────────────────────────── This call is similar to Function 36H (Get Disk Free Space), except that it returns the address of the FAT ID byte in BX instead of the number of available clusters. It is also similar to Function 1CH (Get Drive Data), except that it returns data on the disk in the default drive instead of on the disk in a specified drive. For a description of how MS-DOS stores data on a disk, including a description of the File Allocation Table, see Chapter 3, "MS-DOS Technical Information." ────────────────────────────────────────────────────────────────────────── Warning The FAT ID byte is no longer adequate to identify the type of drive being used. See Chapter 2, "MS-DOS Device Drivers," for more details. ────────────────────────────────────────────────────────────────────────── Macro Definition: def_drive_data macro push ds mov ah,1BH int 21H mov al,byte ptr[bx] pop ds endm Example: The following program displays a message that tells whether the default drive is a floppy disk or a hard disk drive. stdout equ 1 ; msg db "Default drive is " dskt db "disk." fixed db "fixed." crlf db ODH,OAH ; begin: write_handle stdout,msg,17 ; display message jc write_error ; routine not shown def_drive_data ; THIS FUNCTION cmp byte ptr [bx],0F8H ; check FAT ID byte jne disk ; it's a disk write_handle stdout,fixed,6 ; see Function 40H jc write_error ; see Function 40H jmp short all_done ; clean up & go home disk: write_handle stdout,dskt,9 ; see Function 40H all_done: write_handle stdout,crlf,2 ; see Function 40H jc write_error ; routine not shown ──────────────────────────────────────────────────────────────────────────── Get Drive Data (Function 1CH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 1CH DL Drive (0=default, 1=A, etc.) Return: AL 0FFH if drive number is invalid; otherwise, sectors per cluster CX Bytes per sector DX Clusters per drive DS:BX Pointer to FAT ID byte Comments: Function 1CH retrieves data about the disk in the specified drive. DL must contain the drive number (0=default, 1=A, etc.). The data returns in the following registers: Register Contents ────────────────────────────────────────────────────────────────────────── AL Number of sectors in a cluster (allocation unit) CX Number of bytes in a sector DX Number of clusters on the disk ────────────────────────────────────────────────────────────────────────── BX returns the offset (to the segment address in DS) of the first byte of the File Allocation Table (FAT), which identifies the type of disk in the drive: Value Type of Drive ────────────────────────────────────────────────────────────────────────── FF Double-sided disk, 8 sectors per track, 40 tracks per side FE Single-sided disk, 8 sectors per track, 40 tracks per side FD Double-sided disk, 9 sectors per track, 40 tracks per side FC Single-sided disk, 9 sectors per track, 40 tracks per side F9 Double-sided disk, 15 sectors per track, 40 tracks per side F9 Double-sided disk, 9 sectors per track, 80 tracks per side F8 Fixed disk ────────────────────────────────────────────────────────────────────────── If the drive number in DL is invalid, AL returns 0FFH. ────────────────────────────────────────────────────────────────────────── Warning The FAT ID byte is no longer adequate to identify the type of drive being used. See Chapter 2, "MS-DOS Device Drivers," for more details. ────────────────────────────────────────────────────────────────────────── This call is similar to Function 36H (Get Disk Free Space), except that it returns the address of the FAT ID byte in BX instead of the number of available clusters. It is also similar to Function 1BH (Get Default Drive Data), except that it returns data on the disk in the drive specified in DL instead of the disk in the default drive. For a description of how MS-DOS stores data on a disk, including a description of the File Allocation Table, see Chapter 3, "MS-DOS Technical Information." Macro Definition: drive_data macro drive push ds mov dl,drive mov ah,1BH int 21H mov al, byte ptr[bx] pop ds endm Example: The following program displays a message that tells whether drive B is a floppy disk or a hard disk drive. stdout equ 1 : msg db "Drive B is " dskt db "disk." fixed db "fixed." crlf db ODH,OAH ; begin: write_handle stdout,msg,11 ; display message jc write_error ; routine not shown drive_data 2 ; THIS FUNCTION cmp byte ptr [bx],0F8H ; check FAT ID byte jne disk ; it's a disk write_handle stdout,fixed,6 ; see Function 40H jc write_error ; routine not shown jmp all_done ; clean up & go home disk: write_handle stdout,dskt,9 ; see Function 40H all_done: write_handle stdout,crlf,2 ; see Function 40H jc write_error ; routine not shown ──────────────────────────────────────────────────────────────────────────── Random Read (Function 21H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 21H DS:DX Pointer to opened FCB Return: AL 0 = Read completed successfully 1 = End of file, record empty 2 = DTA too small 3 = End of file, partial record Comments: Function 21H reads (into the Disk Transfer Address) the record pointed to by the Relative Record field (offset 21H) of the FCB. DX must contain the offset (from the segment address in DS) of an opened FCB. The Current Block field (offset 0CH) and Current Record field (offset 20H) are set to agree with the Relative Record field (offset 21H). The record is then loaded at the Disk Transfer Address. The record length is taken from the Record Size field (offset 0EH) of the FCB. AL returns a code that describes the processing: Code Meaning ────────────────────────────────────────────────────────────────────────── 0 Read completed successfully 1 End-of-file; no data in the record 2 Not enough room at the Disk Transfer Address to read one record; read canceled 3 End-of-file; a partial record was read and padded to ────────────────────────────────────────────────────────────────────────── Macro Definition: read_ran macro fcb mov dx,offset fcb mov ah,21H int 21H endm Example: The following program prompts for a letter, converts it to its alphabetic sequence (A = 1, B = 2, etc.), then reads and displays the corresponding record from a file named alphabet.dat that is on the disk in drive B. The file contains 26 records, each 28 bytes long. record_size equ 0EH ; offset of Record Size ; field of FCB relative_record equ 21H ; offset of Relative Record ; field of FCB fcb db 2,"ALPHABETDAT" db 26 dup (?) buffer db 28 dup(?),"$" prompt db "Enter letter: $" crlf db 0DH,0AH,"$" ; begin: set_dta buffer ; see Function 1AH open fcb ; see Function 0FH mov fcb[record_size],28 ; set record size get_char: display prompt ; see Function 09H read_kbd_and_echo ; see Function 01H cmp al,0DH ; just a CR? je all_done ; yes, go home sub al,41H ; convert ASCII code ; to record # mov fcb[relative_record],al ; set relative ; record display crlf ; see Function 09H read_ran fcb ; THIS FUNCTION display buffer ; see Function 09H display crlf ; see Function 09H jmp get_char ; get another char. all_done: close fcb ; see Function 10H ──────────────────────────────────────────────────────────────────────────── Random Write (Function 22H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 22H DS:DX Pointer to opened FCB Return: AL 00H = Write completed successfully 01H = Disk full 02H = DTA too small Comments: Function 22H writes (from the Disk Transfer Address) the record pointed to by the Relative Record field (offset 21H) of the FCB. DX must contain the offset from the segment address in DS of an opened FCB. The Current Block (offset 0CH) and Current Record (offset 20H) fields are set to agree with the Relative Record field (offset 21H). This record is then written from the Disk Transfer Address. The record length is taken from the Record Size field (offset 0EH) of the FCB. If the record size is less than a sector, the data at the Disk Transfer Address is written to a buffer. The buffer is written to a disk when it contains a full sector of data, or when a program closes the file, or when it issues Function 0DH (Reset Disk). AL returns a code that describes the processing: Code Meaning ────────────────────────────────────────────────────────────────────────── 0 Write completed successfully 1 Disk is full 2 Not enough room at the Disk Transfer Address to write ────────────────────────────────────────────────────────────────────────── Macro Definition: write_ran macro fcb mov dx,offset fcb mov ah,22H int 21H endm Example: The following program prompts for a letter, converts it to its alphabetic sequence (A = 1, B = 2, etc.), then reads and displays the corresponding record from a file named alphabet.dat that is on the disk in drive B. After displaying the record, it prompts you to enter a changed record. If you type a new record, it is written to the file, but if you just press the ENTER key, the record is not replaced. The file contains 26 records, each 28 bytes long. record_size equ 0EH ; offset of Record Size ; field of FCB relative_record equ 21H ; offset of Relative Record ; field of FCB fcb db 2,"ALPHABETDAT" db 26 dup (?) buffer db 28 dup(?),0DH,0AH,"$" prompt1 db "Enter letter: $" prompt2 db "New record (ENTER for no change): $" crlf db 0DH,0AH,"$" reply db 28 dup (32) blanks db 26 dup (32) ; begin: set_dta buffer ; see Function 1AH open fcb ; see Function 0FH mov fcb[record_size],28 ; set record size get_char: display prompt1 ; see Function 09H read_kbd_and_echo ; see Function 01H cmp al,0DH ; just a carriage return? je all_done ; yes, go home sub al,41H ; convert ASCII ; code to record # mov fcb[relative_record],al ; set relative record display crlf ; see Function 09H read_ran fcb ; THIS FUNCTION display buffer ; see Function 09H display crlf ; see Function 09H display prompt2 ; see Function 09H get_string 27,reply ; see Function 0AH display crlf ; see Function 09H cmp reply[1],0 ; was anything typed ; besides CR? je get_char ; no ; get another char. xor bx,bx ; to load a byte mov bl,reply[1] ; use reply length as ; counter move_string blanks,buffer,26 ; see chapter end move_string reply[2],buffer,bx ; see chapter end write_ran fcb ; THIS FUNCTION jmp get_char ; get another character all_done: close fcb ; see Function 10H ──────────────────────────────────────────────────────────────────────────── Get File Size (Function 23H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 23H DS:DX Pointer to unopened FCB Return: AL 00H = Directory entry found FFH = No directory entry found Comments: Function 23H returns the size of a specified file. DX must contain the offset (from the segment address in DS) of an unopened FCB. If there is a directory entry that matches the specified file, MS-DOS divides the File Size field (offset 10H) of the directory entry by the Record Size field (offset 0EH) of the FCB, puts the result in the Relative Record field (offset 21H) of the FCB, and returns 0 in AL. You must set the Record Size field of the FCB to the correct value before calling this function. If the Record Size field is not an even divisor of the File Size field, the value set in the Relative Record field is rounded up, yielding a value larger than the actual number of records. If this call does not find a matching directory, AL returns FFH. Macro Definition: file_size macro fcb mov dx,offset fcb mov ah,23H int 21H endm Example: The following program prompts for the name of a file, opens the file to fill in the Record Size field of the FCB, issues a File Size system call, and displays the record length and number of records. fcb db 37 dup (?) prompt db "File name: $" msg1 db "Record length: ",0DH,0AH,"$" msg2 db "Records: ",0DH,0AH,"$" crlf db 0DH,0AH,"$" reply db 17 dup(?) ; begin: display prompt ; see Function 09H get_string 17,reply ; see Function 0AH cmp reply[1],0 ; just a CR? jne get_length ; no, keep going jmp all_done ; yes, go home get_length: display crlf ; see Function 09H parse reply[2],fcb ; see Function 29H open fcb ; see Function 0FH file_size fcb ; THIS FUNCTION mov ax,word ptr fcb[33] ; get record length convert ax,10,msg2[9] ; see end of chapter mov ax,word ptr fcb[14] ; get record number convert ax,10,msg1[15] ; see end of chapter display msg1 ; see Function 09H display msg2 ; see Function 09H all_done: close fcb ; see Function 10H ──────────────────────────────────────────────────────────────────────────── Set Relative Record (Function 24H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 24H DS:DX Pointer to opened FCB Return: None AL=00H Relative Record field is modified in FCB. Comments: Function 24H sets the Relative Record field (offset 21H) to the file address specified by the Current Block field (offset 0CH) and Current Record field (offset 20H). DX must contain the offset (from the segment address in DS) of an opened FCB. You use this call to set the file pointer before a Random Read or Write (Functions 21H, 22H, 27H, or 28H). Macro Definition: set_relative_record macro fcb mov dx,offset fcb mov ah,24H int 21H endm Example: The following program copies a file using the Random Block Read and Random Block Write system calls. It speeds the copy by setting the record length equal to the file size and the record count to 1, and by using a buffer of 32 kilobytes. It positions the file pointer by setting the Current Record field (offset 20H) to 1 and using Function 24H (Set Relative Record) to make the Relative Record field (offset 21H) point to the same record that the combination of the Current Block field (offset 0CH) and Current Record field (offset 20H) points to. current_record equ 20H ; offset of Current Record ; field of FCB fil_size equ 10H ; offset of File Size ; field of FCB fcb db 37 dup (?) filename db 17 dup(?) prompt1 db "File to copy: $" ; see Function 09H for prompt2 db "Name of copy: $" ; explanation of $ crlf db 0DH,0AH,"$" file_length dw ? buffer db 32767 dup(?) ; begin: set_dta buffer ; see Function 1AH display prompt1 ; see Function 09H get_string 15,filename ; see Function 0AH display crlf ; see Function 09H parse filename[2],fcb ; see Function 29H open fcb ; see Function 0FH mov fcb[current_record],0 ; set Current Record ; field set_relative_record fcb ; THIS FUNCTION mov ax,word ptr fcb[fil_size] ; get file size mov file_length,ax ; save it for ; ran_block_write ran_block_read fcb,1,ax ; see Function 27H display prompt2 ; see Function 09H get_string 15,filename ; see Function 0AH display crlf ; see Function 09H parse filename[2],fcb ; see Function 29H create fcb ; see Function 16H mov fcb[current_record],0 ; set Current Record ; field set_relative_record fcb ; THIS FUNCTION mov ax,file_length ; get original file ran_block_write fcb,1,ax ; see Function 28H close fcb ; see Function 10H ──────────────────────────────────────────────────────────────────────────── Set Interrupt Vector (Function 25H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 25H AL Interrupt number DS:DX Pointer to interrupt-handling routine Return: None Comments: Function 25H sets the address in the interrupt vector table for the specified interrupt. AL must contain the number of the interrupt. DX must contain the offset (to the segment address in DS) of the interrupt-handling routine. To avoid compatibility problems, programs should never set an interrupt vector directly and should never use Interrupt 25H to read directly from memory. To get a vector, use Function 35H (Get Interrupt Vector), and to set a vector, use Function 25H, unless your program must be compatible with MS-DOS versions earlier than 2.0. Macro Definition: set_vector macro interrupt,handler_start mov al,interrupt mov dx,offset handler_start mov ah,25H endm Example: Because interrupts tend to be machine-specific, no example is shown. ──────────────────────────────────────────────────────────────────────────── Create New PSP (Function 26H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 26H DX Segment address of new PSP Return: None Comments: This function request has been superseded. Use Function 4B00H or 4B03H (Load and Execute Program or Overlay) to run a child process, unless your program must be compatible with MS-DOS versions earlier than 2.0. Function 26H creates a new Program Segment Prefix. DX must contain the segment address where the new PSP is to be created. Macro Definition: create_psp macro seg_addr mov dx,seg_addr mov ah,26H endm Example: Because Functions 4B00H (Load and Execute Program) and 4B03H (Load Overlay) have superseded this function request, no example is shown. ──────────────────────────────────────────────────────────────────────────── Random Block Read (Function 27H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 27H DS:DX Pointer to opened FCB CX Number of blocks to read Return: AL 0 = Read completed successfully 1 = End of file, empty record 2 = DTA too small 3 = End of file, partial record CX Number of blocks read Comments: Function 27H reads one or more records from a specified file to the Disk Transfer Address. DX must contain the offset (to the segment address in DS) of an opened FCB. CX must contain the number of records to read. Reading starts at the record specified by the Relative Record field (offset 21H); you must set this field with Function 24H (Set Relative Record) before calling this function. DOS calculates the number of bytes to read by multiplying the value in CX by the Record Size field (offset 0EH) of the FCB. CX returns the number of records read. The Current Block field (offset 0CH), Current Record field (offset 20H), and Relative Record field (offset 21H) are set to address the next record. If you call this function with CX=0, no records are read. AL returns a code that describes the processing: Code Meaning ────────────────────────────────────────────────────────────────────────── 0 Read completed successfully 1 End-of-file; no data in the record 2 Not enough room at the Disk Transfer Address to read one record; read canceled 3 End-of-file; a partial record was read and padded to ────────────────────────────────────────────────────────────────────────── Macro Definition: ran_block_read macro fcb,count,rec_size mov dx,offset fcb mov cx,count mov word ptr fcb[14],rec_size mov ah,27H int 21H endm Example: The following program copies a file by using Function 27H (Random Block Read). This program speeds the copy process by specifying a record count of 1 and a record length equal to the file size, and by using a buffer of 32 kilobytes; the file is read as a single record (compare to the sample program for Function 28H that specifies a record length of 1 and a record count equal to the file size). current_record equ 20H ; offset of Current Record field fil_size equ 10H ; offset of File Size field ; fcb db 37 dup (?) filename db 17 dup(?) prompt1 db "File to copy: $" ; see Function 09H for prompt2 db "Name of copy: $" ; explanation of $ crlf db 0DH,0AH,"$" file_length dw ? buffer db 32767 dup(?) ; begin: set_dta buffer ; see Function 1AH display prompt1 ; see Function 09H get_string 15,filename ; see Function 0AH display crlf ; see Function 09H parse filename[2],fcb ; see Function 29H open fcb ; see Function 0FH mov fcb[current_record],0 ; set Current ; Record field set_relative_record fcb ; see Function 24H mov ax, word ptr fcb[fil_size] ; get file size mov file_length,ax ; save it ran_block_read fcb,1,ax ; THIS FUNCTION display prompt2 ; see Function 09H get_string 15,filename ; see Function 0AH display crlf ; see Function 09H parse filename[2],fcb ; see Function 29H create fcb ; see Function 16H mov fcb[current_record],0; set current ; Record field set_relative_record fcb ; see Function 24H ran_block_write fcb,1,ax ; see Function 28H close fcb ; see Function 10H ──────────────────────────────────────────────────────────────────────────── Random Block Write (Function 28H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 28H DS:DX Pointer to opened FCB CX Number of blocks to write (0 = set File Size field) Return: AL 00H = Write completed successfully 01H = Disk full 02H = End of segment CX Number of blocks written Comments: Function 28H writes one or more records to a specified file from the Disk Transfer Address. DX must contain the offset (to the segment address in DS) of an opened FCB; CX must contain either the number of records to write or 0. If CX is not 0, the specified number of records is written to the file, starting at the record specified in the Relative Record field (offset 21H) of the FCB. If CX is 0, no records are written, but MS-DOS sets the File Size field (offset 10H) of the directory entry to the value in the Relative Record field (offset 21H) of the FCB. To satisfy this new file size, disk allocation units are allocated or released, as required. MS-DOS calculates the number of bytes to write by multiplying the value in CX by the Record Size field (offset 0EH) of the FCB. CX returns the number of records written; the Current Block field (offset 0CH), Current Record field (offset 20H), and Relative Record (offset 21H) field are set to address the next record. AL returns a code that describes the processing: Code Meaning ────────────────────────────────────────────────────────────────────────── 0 Write completed successfully 1 Disk full. No records written 2 Not enough room at the Disk Transfer Address to write ────────────────────────────────────────────────────────────────────────── Macro Definition: ran_block_write macro fcb,count,rec_size mov dx,offset fcb mov cx,count mov word ptr fcb[14],rec_size mov ah,28H int 21H endm Example: The following program copies a file using Function 27H (Random Block Read) and Function 28H (Random Block Write). This program speeds the copy process by specifying a record count equal to the file size and a record length of 1, and by using a buffer of 32 kilobytes. The file is copied quickly with one disk access each to read and write (compare to the sample program of Function 27H, which specifies a record count of 1 and a record length equal to file size). current_record equ 20H ; offset of Current Record field fil_size equ 10H ; offset of File Size field ; fcb db 37 dup (?) filename db 17 dup(?) prompt1 db "File to copy: $" ; see Function 09H for prompt2 db "Name of copy: $" ; explanation of $ crlf db 0DH,0AH,"$" num_recs dw ? buffer db 32767 dup(?) ; begin: set_dta buffer ; see Function 1AH display prompt1 ; see Function 09H get_string 15,filename ; see Function 0AH display crlf ; see Function 09H parse filename[2],fcb ; see Function 29H open fcb ; see Function 0FH mov fcb[current_record],0; set Current Record field set_relative_record fcb ; see Function 24H mov ax, word ptr fcb[fil_size] ; get file size mov num_recs,ax ; save it ran_block_read fcb,num_recs,1 ; THIS FUNCTION display prompt2 ; see Function 09H get_string 15,filename ; see Function 0AH display crlf ; see Function 09H parse filename[2],fcb ; see Function 29H create fcb ; see Function 16H mov fcb[current_record],0 ; set Current ; Record field set_relative_record fcb ; see Function 24H ran_block_write fcb,num_recs,1 ; see Function 28H close fcb ; see Function 10H ──────────────────────────────────────────────────────────────────────────── Parse File Name (Function 29H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 29H AL Controls parsing (see text) DS:SI Pointer to string to parse ES:DI Pointer to buffer for unopened FCB Return: AL 00H = No wildcard characters 01H = Wildcard characters used FFH = Drive letter invalid DS:SI Pointer to first byte past string that was parsed ES:DI Pointer to unopened FCB Comments: Function 29H parses a string for a filename of the form drive:filename.extension. SI must contain the offset (to the segment address in DS) of the string to parse; DI must contain the offset (to the segment address in ES) of an area of memory large enough to hold an unopened FCB. If the string contains a valid filename, this call creates a corresponding unopened FCB at ES:DI. AL controls the parsing. Bits 4-7 must be 0; bits 0-3 have the following meaning: Table 1.20 Bit Values for Function 29H ╓┌─┌───────────┌────────────┌────────────────────────────────────────────────╖ Bit Value Meaning ────────────────────────────────────────────────────────────────────────── 0 0 Stops parsing if a file separator is encountered 1 Ignores leading separators 1 0 Sets the drive number in the FCB to 0 (current drive) if the string does not contain a drive number 1 Leaves the drive number in the FCB unchanged if the string does not contain a drive number 2 0 Sets the filename in the FCB to eight blanks if the string does not contain a filename 1 Leaves the filename in the FCB unchanged if the string does not contain a filename 3 0 Sets the extension in the FCB to three blanks if the string does not contain an extension Bit Value Meaning ────────────────────────────────────────────────────────────────────────── the string does not contain an extension 1 Leaves the extension in the FCB unchanged if the ────────────────────────────────────────────────────────────────────────── If the string contains a filename or extension that includes an asterisk (*), all remaining characters in the name or extension are set to question marks (?). Filename Separators: : ; . , = + / " [ ] \ < > | space tab Filename terminators include all the filename separators, plus any control character. A filename cannot contain a filename terminator, since, if the call encounters one, parsing stops. If the string contains a valid filename: ■ AL returns 1 if the filename or extension contains a wildcard character (* or ?); AL returns 0 if neither the filename nor extension contains a wildcard character. ■ DS:SI points to the first character following the parsed string. ■ ES:DI points to the first byte of the unopened FCB. If the drive letter is invalid, AL returns FFH. If the string does not contain a valid filename, ES:DI+1 points to a blank. Macro Definition: parse macro string,fcb mov si,offset string mov di,offset fcb push es push ds pop es mov al,0FH ; bits 0-3 on mov ah,29H int 21H pop es endm Example: The following program verifies the existence of the file named in reply to the prompt. fcb db 37 dup (?) prompt db "Filename: $" reply db 17 dup(?) yes db "File exists",0DH,0AH,"$" no db "File does not exist",0DH,0AH,"$" crlf db 0DH,0AH,"$" ; begin: display prompt ; see Function 09H get_string 15,reply ; see Function 0AH parse reply[2],fcb ; THIS FUNCTION display crlf ; see Function 09H search_first fcb ; see Function 11H cmp al,0FFH ; dir. entry found? je not_there ; no display yes ; see Function 09H jmp return not_there: display no ──────────────────────────────────────────────────────────────────────────── Get Date (Function 2AH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 2AH Return: CX Year (1980-2099) DH Month (1-12) DL Day (1-31) AL Day of week (0=Sun., 6=Sat.) Comments: Function 2AH returns the current date set in the operating system as binary numbers in CX and DX: Register Contents ────────────────────────────────────────────────────────────────────────── CX Year (1980-2099) DH Month (1=January, 2=February, etc.) DL Day of month (1-31) AL Day of week (0=Sunday, 1=Monday, etc.) ────────────────────────────────────────────────────────────────────────── Macro Definition: get_date macro mov ah,2AH int 21H endm Example: The following program gets the date, increments the day, increments the month or year, if necessary, and sets the new date. month db 31,28,31,30,31,30,31,31,30,31,30,31 ; begin: get_date ; THIS FUNCTION inc dl ; increment day xor bx,bx ; so BL can be used as index mov bl,dh ; move month to index register dec bx ; month table starts with 0 cmp dl,month[bx] ; past end of month? jle month_ok ; no, set new date mov dl,1 ; yes, set day to 1 inc dh ; and increment month cmp dh,12 ; past end of year? jle month_ok ; no, set new date mov dh,1 ; yes, set month to 1 inc cx ; increment year month_ok: set_date cx,dh,dl ; see Function 2AH ──────────────────────────────────────────────────────────────────────────── Set Date (Function 2BH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 2BH CX Year (1980-2099) DH Month (1-12) DL Day (1-31) Return: AL 00H = Date was valid FFH = Date was invalid Comments: Function 2BH sets the date in the operating system (and in the CMOS clock, if one exists). Registers CX and DX must contain a valid date in binary: Register Contents ────────────────────────────────────────────────────────────────────────── CX Year (1980-2099) DH Month (1=January, 2=February, etc.) DL Day of month (1-31) ────────────────────────────────────────────────────────────────────────── If the date is valid, the call sets it and AL returns 0. If the date is not valid, the function aborts and AL returns FFH. Macro Definition: set_date macro year,month,day mov cx,year mov dh,month mov dl,day mov ah,2BH int 21H endm Example: The following program gets the date, increments the day, increments the month or year, if necessary, and sets the new date. month db 31,28,31,30,31,30,31,31,30,31,30,31 ; begin: get_date ; see Function 2AH inc dl ; increment day xor bx,bx ; so BL can be used as index mov bl,dh ; move month to index register dec bx ; month table starts with 0 cmp dl,month[bx] ; past end of month? jle month_ok ; no, set the new date mov dl,1 ; yes, set day to 1 inc dh ; and increment month cmp dh,12 ; past end of year? jle month_ok ; no, set the new date mov dh,1 ; yes, set the month to 1 inc cx ; increment year month_ok: set_date cx,dh,dl ; THIS FUNCTION ──────────────────────────────────────────────────────────────────────────── Get Time (Function 2CH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 2CH Return: CH Hour (0-23) CL Minutes (0-59) DH Seconds (0-59) DL Hundredths (0-99) Comments: Function 2CH returns the current time set in the operating system (and sets the CMOS clock, if one exists) as binary numbers in CX and DX: Register Contents ────────────────────────────────────────────────────────────────────────── CH Hour (0-23) CL Minutes (0-59) DH Seconds (0-59) DL Hundredths of a second (0-99) ────────────────────────────────────────────────────────────────────────── Depending on how your hardware keeps time, some of these fields may be irrelevant. As an example, many CMOS clock chips do not resolve more than seconds. In such a case, the value in DL will probably always be 0. Macro Definition: get_time macro mov ah,2CH int 21H endm Example: The following program displays the time continuously until you press any key. time db "00:00:00.00",0DH,"$" ; begin: get_time ; THIS FUNCTION byte_to_dec ch,time ; see end of chapter byte_to_dec cl,time[3] ; see end of chapter byte_to_dec dh,time[6] ; see end of chapter byte_to_dec dl,time[9] ; see end of chapter display time ; see Function 09H check_kbd_status ; see Function 0BH cmp al,0FFH ; has a key been pressed? je return ; yes, terminate jmp begin ; no, display time ──────────────────────────────────────────────────────────────────────────── Set Time (Function 2DH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 2DH CH Hour (0-23) CL Minutes (0-59) DH Seconds (0-59) DL Hundredths (0-99) Return: AL 00H = Time was valid FFH = Time was invalid Comments: Function 2DH sets the time in the operating system. Registers CX and DX must contain a valid time in binary: Register Contents ────────────────────────────────────────────────────────────────────────── CH Hour (0-23) CL Minutes (0-59) DH Seconds (0-59) DL Hundredths of a second (0-99) ────────────────────────────────────────────────────────────────────────── Depending on how your hardware keeps time, some of these fields may be irrelevant. As an example, many CMOS clock chips do not resolve more than seconds. In such a case, the value in DL will not be relevant. If the time is valid, the call sets it and AL returns 0. If the time is not valid, the function aborts and AL returns FFH. Macro Definition: set_time macro hour,minutes,seconds,hundredths mov ch,hour mov cl,minutes mov dh,seconds mov dl,hundredths mov ah,2DH int 21H endm Example: The following program sets the system clock to 0 and displays the time continuously. When you type a character, the display freezes; when you type another character, the clock is reset to 0 and the display starts again. time db "00:00:00.00",0DH,0AH,"$" ; begin: set_time 0,0,0,0 ; THIS FUNCTION read_clock: get_time ; see Function 2CH byte_to_dec ch,time ; see end of chapter byte_to_dec cl,time[3] ; see end of chapter byte_to_dec dh,time[6] ; see end of chapter byte_to_dec dl,time[9] ; see end of chapter display time ; see Function 09H dir_console_io 0FFH ; see Function 06H cmp al,00H ; was a char. typed? jne stop ; yes, stop the timer jmp read_clock ; no keep timer on stop: read_kbd ; see Function 08H jmp begin ; keep displaying time ──────────────────────────────────────────────────────────────────────────── Set/Reset Verify Flag (Function 2EH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 2EH AL 0 = Do not verify 1 = Verify Return: None Comments: Function 2EH tells MS-DOS whether or not to verify each disk write. If AL is 1, verify is on; if AL is 0, verify is off. MS-DOS checks this flag each time it writes to a disk. The flag is normally off; you may wish to turn it on when writing critical data to disk. Because disk errors are rare and verification slows writing, you will probably want to leave it off at other times. You can check the setting with Function 54H (Get Verify State). Macro Definition: verify macro switch mov al,switch mov ah,2EH int 21H 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 32 kilobytes. on equ 1 off equ 0 ; 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 ; THIS FUNCTION mov cx,6 ; copy 60 sectors ; 6 times copy: push cx ; save counter abs_disk_read 0,buffer,60,first ; see Int 25H abs_disk_write 1,buffer,64,first ; see Int 26H add first,60 ; do next 60 sectors pop cx ; restore counter loop copy ; do it again verify off ; THIS FUNCTION ──────────────────────────────────────────────────────────────────────────── Get Disk Transfer Address (Function 2FH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 2FH Return: ES:BX Pointer to Disk Transfer Address Comments: Function 2FH returns the segment address of the current Disk Transfer Address in ES and the offset in BX. Macro Definition: get_dta macro mov ah,2fH int 21H endm Example: The following program displays the current Disk Transfer Address in the form: segment:offset. message db "DTA -- : ",0DH,0AH,"$" sixteen db 10H temp db 2 dup (?) ; begin: get_dta ; THIS FUNCTION mov word ptr temp,ex ; To access each byte convert temp[1],sixteen,message[07H] ; See end of convert temp,sixteen,message[09H] ; chapter for convert bh,sixteen,message[0CH] ; description convert bl,sixteen,message[0EH] ; of CONVERT display message ; See Function 09H ──────────────────────────────────────────────────────────────────────────── Get MS-DOS Version Number (Function 30H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 30H Return: AL Major version number AH Minor version number BH OEM serial number BL:CX 24-bit user (serial) number Comments: Function 30H returns the MS-DOS version number. AL returns the major version number; AH returns the minor version number. (For example, MS-DOS 3.0 returns 3 in AL and 0 in AH.) If AL returns 0, the MS-DOS version is earlier than 2.0. Macro Definition: get_version macro mov ah,30H int 21H endm Example: The following program displays the MS-DOS version if it is 1.28 or greater. message db "MS-DOS Version . ",0DH,0AH,"$" ten db 0AH ; For CONVERT ; begin: get_version ; THIS FUNCTION cmp al,0 ; 1.28 or later? jng return ; No, go home convert al,ten,message[0FH] ; See end of chapter convert ah,ten,message[12H] ; for description display message ; See Function 9 ──────────────────────────────────────────────────────────────────────────── Keep Process (Function 31H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 31H AL Return code DX Memory size, in paragraphs Return: None Comments: Function 31H makes a program remain resident after it terminates. You can use it to install device-specific interrupt handlers. But unlike Interrupt 27H (Terminate But Stay Resident), this function request allows more than 64K bytes to remain resident and does not require CS to contain the segment address of the Program Segment Prefix. You should use Function 31H to install a resident program unless your program must be compatible with MS-DOS versions earlier than 2.0. DX must contain the number of paragraphs of memory required by the program (one paragraph = 16 bytes). AL contains an exit code. Be careful when using this function with .exe programs. The value in DX must be the total size to remain resident, not just the size of the code segment which is to remain resident. A typical error is to forget about the 100H-byte program-header-prefix and give a value in DX that doesn't account for the size of this prefix. MS-DOS terminates the current process and tries to set the memory allocation to the number of paragraphs in DX. No other allocation blocks belonging to the process are released. By using Function 4DH (Get Return Code of Child Process), the parent process can retrieve the process's exit code from AL. (You can test this exit code by using the if command with errorlevel.) Macro Definition: keep_process macro return_code,last_byte mov al,return_code mov dx,offset last_byte mov cl,4 shr dx,cl inc dx mov ah,31H int 21H endm Example: Because the most common use of this call is to install a machine-specific routine, an example is not shown. The macro definition, however, shows the calling syntax. ──────────────────────────────────────────────────────────────────────────── CONTROL+C Check (Function 33H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 33H AL 0 = Get state of CONTROL+C 1 = Set state of CONTROL+C 5 = Query DOS boot drive DL (if AL=1) 0 = Off 1 = On Return: DL (if AL=0) 0 = Off 1 = On DL (if AL=5) 1 = A, 2 = B, etc. AL FFH = error (AL was neither 0, 1, nor 5 when call was made) Comments: Function 33H gets or sets the state of CONTROL+C (or CONTROL+BREAK for IBM compatibles) checking in MS-DOS and can query the DOS boot drive. AL must contain a code that specifies the requested action: Code Meaning ────────────────────────────────────────────────────────────────────────── 0 Current state of CONTROL+C checking in DL 1 Set state of CONTROL+C checking to the value in DL 5 Query DOS boot drive in DL ────────────────────────────────────────────────────────────────────────── If AL is 0, DL returns the current state (0=off, 1=on). If AL is 1, the value in DL specifies the state to be set (0=off, 1=on). If AL is neither 0, 1, nor 5, AL returns FFH and the state of CONTROL+C checking is unaffected. MS-DOS normally checks for CONTROL+C only when carrying out certain function requests in the 01H through 0CH group (see the description of specific calls for details). When CONTROL+C checking is on, MS-DOS checks for CONTROL+C when carrying out any function request. For example, if CONTROL+C checking is off, all disk I/O proceeds without interruption, but if it is on, the CONTROL+C interrupt is issued at the function request that initiates the disk operation. ────────────────────────────────────────────────────────────────────────── Note Programs that use Function 06H (Direct Console I/O) or 07H (Direct Console Input) to read CONTROL+C as data must ensure that the CONTROL+C checking is off. ────────────────────────────────────────────────────────────────────────── Macro Definition: ctrl_c_ck macro action,state mov al,action mov dl,state mov ah,33H int 21H endm Example: The following program displays a message that tells whether CONTROL+C checking is on or off: message db "CONTROL+C checking ","$" on db "on","$",0DH,0AH,"$" off db "off","$",0DH,0AH,"$" ; begin: display message ; See Function 09H ctrl_c_ck 0 ; THIS FUNCTION cmp dl,0 ; Is checking off? jg ck_on ; No display off ; See Function 09H jmp return ; Go home ck_on: display on ; See Function 09H To query the DOS boot drive value, add the following programs segment: mov AH,33H ; Query DOS value mov AL,05H ; DOS boot drive int 21H jc ERROR ; DL=Boot drive (A=1) ──────────────────────────────────────────────────────────────────────────── Get Interrupt Vector (Function 35H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 35H AL Interrupt number Return: ES:BX Pointer to interrupt routine Comments: Function 35H gets the address from the interrupt-vector table for the specified interrupt. AL must contain the number of an interrupt. ES returns the segment address of the interrupt handler; BX returns the offset. To avoid compatibility problems, programs should never read an interrupt vector directly from memory, nor set an interrupt vector by writing it into memory. Use this function request to get a vector and Function 25H (Set Interrupt Vector) to set a vector, unless your program must be compatible with MS-DOS versions earlier than 2.0. Macro Definition: get_vector macro interrupt mov al,interrupt mov ah,35H int 21H endm Example: The following program displays the segment and offset (CS:IP) for the handler for Interrupt 25H (Absolute Disk Read). message db "Interrupt 25H -- CS:0000 IP:0000" db 0DH,0AH,"$" vec_seg db 2 dup (?) vec_off db 2 dup (?) ; begin: push es ; save ES get_vector 25H ; THIS FUNCTION mov ax,es ; INT25H segment in AX pop es ; save ES convert ax,16,message[20] ; see end of chapter convert bx,16,message[28] ; see end of chapter display message ; See Function 9 ──────────────────────────────────────────────────────────────────────────── Get Disk Free Space (Function 36H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 36H DL Drive (0=default, 1=A, etc.) Return: AX 0FFFFH if drive number is invalid; otherwise, sectors per cluster BX Available clusters CX Bytes per sector DX Clusters per drive Comments: Function 36H returns the number of clusters available on the disk in the specified drive and the information necessary to calculate the number of bytes available on the disk. DL must contain a drive number (0=default, 1=A, etc.). If the drive number is valid, MS-DOS returns the information in the following registers: Register Contents ────────────────────────────────────────────────────────────────────────── AX Sectors per cluster BX Available clusters CX Bytes per sector DX Total clusters ────────────────────────────────────────────────────────────────────────── If the drive number is invalid, AX returns 0FFFFH. This call supersedes Functions 1BH and 1CH in earlier MS-DOS versions. Macro Definition: get_disk_space macro drive mov dl,drive mov ah,36H int 21H endm Example: The following program displays space information for the disk in drive B. message db " clusters on drive B.",0DH,0AH ; DX db " clusters available.",0DH,0AH ; BX db " sectors per cluster.",0DH,0AH ; AX db " bytes per sector,",0DH,0AH,"$" ; CX ; begin: get_disk_space 2 ; THIS FUNCTION convert ax,10,message[55] ; see end of chapter convert bx,10,message[28] ; see end of chapter convert cx,10,message[83] ; see end of chapter convert dx,10,message ; see end of chapter display message ; See Function 09H ──────────────────────────────────────────────────────────────────────────── Get Country Data (Function 38H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 38H AL 00H = Current country 1-0FEH = Country code 0FFH = BX contains country code BX (if AL = 0FFH) Country code 255 or higher DS:DX Pointer to 32-byte memory area Return: Carry set: AX 2 = Invalid country code DS:DX Segment:offset pointer to 32-byte memory area Carry not set: BX Country code Comments: Function 38H gets the country-dependent information that MS-DOS uses to control the keyboard and display, or it sets the currently defined country (to set the country code, see the next function request description, Set Country Data). To get the information, DX must contain the offset (from the segment address in DS) of a 32-byte memory area to which the country data returns. AL specifies the country code: Value in AL Meaning ────────────────────────────────────────────────────────────────────────── 00H Retrieves information about the country currently set 1 to 0FEH Retrieves information about the country identified by this code 0FFH Retrieves information about the country identified by the code in BX ────────────────────────────────────────────────────────────────────────── BX must contain the country code if the code is 255 or greater. The country code is usually the international telephone-prefix code. The country-dependent information returns in the following form: Offset Hex Decimal Field Name Length in bytes ────────────────────────────────────────────────────────────────────────── 00H 0 Date format 2 (word) 02H 2 Currency symbol 5 (ASCIZ string) 07H 7 Thousands separator 2 (ASCIZ string) 09H 9 Decimal separator 2 (ASCIZ string) 0BH 11 Date separator 2 (ASCIZ string) 0DH 13 Time separator 2 (ASCIZ string) 0FH 15 Bit field 1 10H 16 Currency places 1 11H 17 Time format 1 12H 18 Case-map call address 4 (DWORD) 16H 22 Data-list separator 2 (ASCIZ string) 18H 24 Reserved 10 ────────────────────────────────────────────────────────────────────────── Date Format: 0 = USA (month/day/year) 1 = Europe (day/month/year) 2 = Japan (year/month/day) Bit Field: Bit Value Meaning ────────────────────────────────────────────────────────────────────────── 0 0 Currency symbol precedes amount 1 Currency symbol follows amount 1 0 No space between symbol and amount 1 One space between symbol and amount ────────────────────────────────────────────────────────────────────────── All other bits are undefined. Time Format: 0 = 12-hour clock 1 = 24-hour clock Currency Places: Specifies the number of places that appear after the decimal point on currency amounts. Case-Mapping Call Address: Specifies the segment and offset of a FAR procedure that performs country-specific lowercase-to-uppercase mapping on character values from 80H to 0FFH. You call it with the character to be mapped in AL. If there is an uppercase code for the character, it is returned in AL; if there is not, or if you call it with a value less than 80H in AL, AL returns unchanged. AL and the FLAGS are the only altered registers. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 2 Invalid country code (no table for it). ────────────────────────────────────────────────────────────────────────── Macro Definition: get_country macro country,buffer local gc_01 mov dx,offset buffer mov ax,country cmp ax,OFFH jl gc_01 mov al,OFFh mov bx,country gc_01: mov ah,38h int 21H endm Example: The following program displays the time and date in the format appropriate to the current country code, and the number 999,999 and 99/100 as a currency amount with the proper currency symbol and separators. time db " : : ",5 dup (20H),"$" date db " / / ",5 dup (20H),"$" number db "999?999?99",0DH,0AH,"$" data_area db 32 dup (?) ; begin: get_country 0,data_area ; THIS FUNCTION get_time ; See Function 2CH byte_to_dec ch,time ; See end of chapter byte_to_dec cl,time[03H] ; for description of byte_to_dec dh,time[06H] ; CONVERT macro get_date ; See Function 2AH sub cx,1900 ; Want last 2 digits byte_to_dec cl,date[06H] ; See end of chapter cmp word ptr data_area,0 ; Check country code jne not_usa ; It's not USA byte_to_dec dh,date ; See end of chapter byte_to_dec dl,date[03H] ; See end of chapter jmp all_done ; Display data not_usa: byte_to_dec dl,date ; See end of chapter byte_to_dec dh,date[03H] ; See end of chapter all_done: mov al,data_area[07H] ; Thousand separator mov number[03H],al ; Put in NUMBER mov al,data_area[09H] ; Decimal separator mov number[07H],al ; Put in AMOUNT display time ; See Function 09H display date ; See Function 09H display_char data_area[02H] ; See Function 02H display number ; See Function 09H ──────────────────────────────────────────────────────────────────────────── Set Country Data (Function 38H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 38H DX = -1 (0FFFFH) AL Country code less than 255, or 0FFH if the country code is in BX BX (if AL=0FFH) Country code 255 or higher Return: Carry set: AX 2 = Invalid country code Carry not set: No error Comments: Function 38H sets the country code that MS-DOS uses to control the keyboard and the display, or it retrieves the country-dependent information (to get the country data, see the previous function request description, Get Country Data). To set the information, DX must contain 0FFFFH. AL must contain either the country code, if it is less than 255, or 255 to indicate that the country code is in BX. If AL contains 0FFH, BX must contain the country code. The country code is usually the international telephone prefix-code. See "Get Country Data" for a description of the country data and how it is used. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 2 Invalid country code (no table for it). ────────────────────────────────────────────────────────────────────────── Macro Definition: set_country macro country local sc_01 mov dx,0FFFFH mov ax,country cmp ax,0FFH jl sc_01 mov bx,country mov al,0ffh sc_01: mov ah,38H int 21H endm Example: The following program sets the country code to the United Kingdom (44). uk equ 44 ; begin: set_country uk ; THIS FUNCTION jc error ; routine not shown ──────────────────────────────────────────────────────────────────────────── Create Directory (Function 39H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 39H DS:DX Pointer to pathname Return: Carry set: AX 2 = File not found 3 = Path not found 5 = Access denied Carry not set: No error Comments: Function 39H creates a new subdirectory. DX must contain the offset (from the segment address in DS) of an ASCIZ string that specifies the pathname of the new subdirectory. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 2 File not found 3 Path not found 5 No room in the parent directory, a file with the same name exists in the current directory, or the path ────────────────────────────────────────────────────────────────────────── Macro Definition: make_dir macro path mov dx,offset path mov ah,39H int 21H endm Example: The following program adds a subdirectory named new_dir to the root directory on the disk in drive B and changes the current directory to new_dir. The program then changes the current directory back to the original directory and then deletes new_dir. It displays the current directory after each step to confirm the changes. old_path db "b:",0,63 dup (?) new_path db "b:\new_dir",0 buffer db "b:",0,63 dup (?) ; begin: get_dir 2,old_path[03H] ; See Function 47H jc error_get ; Routine not shown display_asciz old_path ; See end of chapter make_dir new_path ; THIS FUNCTION jc error_make ; Routine not shown change_dir new_path ; See Function 3BH jc error_change ; Routine not shown get_dir 2,buffer[03H] ; See Function 47H jc error_get ; Routine not shown display_asciz buffer ; See end of chapter change_dir old_path ; See Function 3BH jc error_change ; Routine not shown rem_dir new_path ; See Function 3AH jc error_rem ; Routine not shown get_dir 2,buffer[03H] ; See Function 47H jc error_get ; Routine not shown display_asciz buffer ; See end of chapter ──────────────────────────────────────────────────────────────────────────── Remove Directory (Function 3AH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 3AH DS:DX Pointer to pathname Return: Carry set: AX 2 = File not found 3 = Path not found 5 = Access denied 16 = Current directory Carry not set: No error Comments: Function 3AH deletes a subdirectory. DX must contain the offset (from the segment address in DS) of an ASCIZ string that specifies the pathname of the subdirectory you want to delete. The subdirectory must not contain any files. You cannot erase the current directory. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 2 File not found 3 Path not found 5 Directory not empty, or path doesn't specify a directory, or it specifies the root directory, or it is invalid 16 Path specifies current directory ────────────────────────────────────────────────────────────────────────── Macro Definition: rem_dir macro path mov dx,offset path mov ah,3AH int 21H endm Example: The following program adds a subdirectory named new_dir to the root directory on the disk in drive B and changes the current directory to new_dir. The program then changes the current directory back to the original directory and deletes new_dir. It displays the current directory after each step to confirm the changes. old_path db "b:",0,63 dup (?) new_path db "b:\new_dir",0 buffer db "b:",0,63 dup (?) ; begin: get_dir 2,old_path[03H] ; See Function 47H jc error_get ; Routine not shown display_asciz old_path ; See end of chapter make_dir new_path ; See Function 39H jc error_make ; Routine not shown change_dir new_path ; See Function 3BH jc error_change ; Routine not shown get_dir 2,buffer[03H] ; See Function 47H jc error_get ; Routine not shown display_asciz buffer ; See end of chapter change_dir old_path ; See Function 3BH jc error_change ; Routine not shown rem_dir new_path ; THIS FUNCTION jc error_rem ; Routine not shown get_dir 2,buffer[03H] ; See Function 47H jc error_get ; Routine not shown display_asciz buffer ; See end of chapter ──────────────────────────────────────────────────────────────────────────── Change Current Directory (Function 3BH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 3BH DS:DX Pointer to pathname Return: Carry set: AX 2 = File not found 3 = Path not found Carry not set: No error Comments: Function 3BH changes the current directory. DX must contain the offset (from the segment address in DS) of an ASCIZ string that specifies the pathname of the new current directory. The directory string is limited to 64 characters. If any member of the path doesn't exist, the path is unchanged. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 2 File not found 3 Path either doesn't exist or it specifies a file ────────────────────────────────────────────────────────────────────────── Macro Definition: change_dir macro path mov dx,offset path mov ah,3BH int 21H endm Example: The following program adds a subdirectory named new_dir to the root directory that is on the disk in drive B and changes the current directory to new_dir. The program then changes the current directory back to the original directory and deletes new_dir. It displays the current directory after each step to confirm the changes. old_path db "b:",0,63 dup (?) new_path db "b:\new_dir",0 buffer db "b:",0,63 dup (?) ; begin: get_dir 2,old_path[03H] ; See Function 47H jc error_get ; Routine not shown display_asciz old_path ; See end of chapter make_dir new_path ; See Function 39H jc error_make ; Routine not shown change_dir new_path ; THIS FUNCTION jc error_change ; Routine not shown get_dir 2,buffer[03H] ; See Function 47H jc error_get ; Routine not shown display_asciz buffer ; See end of chapter change_dir old_path ; See Function 3BH jc error_change ; Routine not shown rem_dir new_path ; See Function 3AH jc error_rem ; Routine not shown get_dir 2,buffer[03H] ; See Function 47H jc error_get ; Routine not shown display_asciz buffer ; See end of chapter ──────────────────────────────────────────────────────────────────────────── Create Handle (Function 3CH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 3CH DS:DX Pointer to pathname CX File attribute Return: Carry set: AX 2 = File not found 3 = Path not found 4 = Too many open files 5 = Access denied Carry not set: AX Handle Comments: Function 3CH creates a file and assigns it the first available handle. DX must contain the offset (from the segment address in DS) of an ASCIZ string that specifies the pathname of the file to be created. CX must contain the attribute to be assigned to the file, as described under "File Attributes" earlier in this chapter. If the specified file does not exist, this function creates it. But if the file already exists, it is truncated to a length of 0. Function 3CH then assigns the attribute in CX to the file and opens it for read/write. AX returns the file handle. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 2 File not found 3 Path is invalid 4 Too many open files (no handle available) 5 Directory is full, a directory with the same name exists, or a file with the same name exists with more ────────────────────────────────────────────────────────────────────────── Macro Definition: create_handle macro path,attrib mov dx,offset path mov cx,attrib mov ah,3CH int 21H endm Example: The following program creates a file named dir.tmp, containing the name and extension of each file in the current directory, on the disk in drive B. srch_file db "b:*.*",0 tmp_file db "b:dir.tmp",0 buffer db 43 dup (?) handle dw ? ; begin: set_dta buffer ; See Function 1AH find_first_file srch_file,16H ; See Function 4EH cmp ax,12H ; Directory empty? je all_done ; Yes, go home create_handle tmp_file,0 ; THIS FUNCTION jc error ; Routine not shown mov handle,ax ; Save handle write_it: write_handle handle,buffer[1EH],12 ; Function 40H find_next_file ; See Function 4FH cmp ax,12H ; Another entry? je all_done ; No, go home jmp write_it ; Yes, write record all_done: close_handle handle ; See Function 3EH ──────────────────────────────────────────────────────────────────────────── Open Handle (Function 3DH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 3DH AL Access code (see text) DS:DX Pointer to pathname Return: Carry set: AX 2 = File not found 3 = Path not found 4 = Too many open files 5 = Access denied 12 = Invalid access Carry not set: No error Comments: Function 3DH opens any file, including hidden and system files, for input or output. DX contains the offset (from the segment address in DS) of an ASCIZ string that specifies the pathname of the file to be opened. AL contains a code that specifies how the file is to be opened. This code is described later under "Controlling Access to the File." If there is no error, AX returns the file handle. MS-DOS sets the read/write pointer to the first byte of the file. Controlling Access to the File The value in AL is made up of three parts that specify whether the file is to be opened for read, write, or both (access code); what access other processes have to the file (sharing mode); and whether a child process inherits the file (inherit bit). ┌───┬───────────┬───────────────┐ Bit │ 7 │ 6 5 4 │ 3 2 1 0 │ └───┴───────────┴───────────────┘ \_/ \_________/ \______________/ │ │ │ │ │ └────────> Access code │ │ │ └──────────────────────> Sharing mode │ └──────────────────────────────> Inherit bit Inherit Bit The high-order bit (bit 7) specifies whether the file is inherited by a child process created with Function 4B00H or 4B03H (Load and Execute Program or Overlay). If the bit is 0, the child process inherits the file; if the bit is 1, it doesn't. Sharing Mode The sharing mode bits (bits 4-6) specify what access, if any, other processes have to the open file. It can have the following values: Table 1.21 Sharing Mode Bit Values Bits 4-6 Sharing Mode Description ────────────────────────────────────────────────────────────────────────── 000 Compatibility On a given machine, any process can open the file any number of times with this mode. Fails if the file has been opened with any of the other sharing modes. 001 Deny both Fails if the file has been opened in compatibility mode or for read or write access, even if by the current process. 010 Deny write Fails if the file has been opened in compatibility mode or for write access by any other process. 011 Deny read Fails if the file has been opened in compatibility mode or for read access by any other process. 100 Deny none Fails if the file has been opened in ────────────────────────────────────────────────────────────────────────── Access Code The access code (bits 0-3) specifies how the file is to be used. It can have the following values: Table 1.22 Access Code Bit Values Access Bits 0-3 Allowed Description ────────────────────────────────────────────────────────────────────────── 0000 Read Fails if the file has been opened in deny read or deny both sharing mode. 0001 Write Fails if the file has been opened in deny write or deny both sharing mode. 0010 Both Fails if the file has been opened in deny read, ────────────────────────────────────────────────────────────────────────── If there is an error, the carry flag (CF) is set and the error code is returned in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 2 Specified file is invalid or doesn't exist 3 Specified path is invalid or doesn't exist 4 No handles are available in the current process or the internal system tables are full 5 Program attempted to open a directory or VolumeID, or tried to open a read-only file for writing 12 Access code (bits 0-3 of AL) not 0, 1, or 2 ────────────────────────────────────────────────────────────────────────── If this system call fails because of a file-sharing error, MS-DOS issues Interrupt 24H with error code 2 (Drive Not Ready). A subsequent Function 59H (Get Extended Error) returns the extended error code that specifies a sharing violation. When opening a file, it is important to inform MS-DOS of any operations that other processes may perform on this file (sharing mode). The default (compatibility mode) denies all other processes access to the file, unless they also attempt to open the file in compatibility mode. The following table shows the effect of opening a file with compatibility mode set: Type of File Opening Read-Only File Not Read-Only ────────────────────────────────────────────────────────────────────────── First open for read, write, or Succeeds Succeeds both by machine/process "N" Subsequent opens by machine or Succeeds Succeeds process "N" An open by another machine or Succeeds Fails process ────────────────────────────────────────────────────────────────────────── Files may be read-only with the MS-DOS attrib command or by a read-only share over the network. It may be all right for other processes to continue to read the file while your process is operating on it. In this case, you should specify "Deny Write," which inhibits other processes from writing to your files but allows them to read from these files. Similarly, it is important for you to specify what operations your process will perform ("Access" mode). If another process has the file open with any sharing mode other than "Deny" mode, then the default mode ("Read/Write") causes the open request to fail. If you only want to read the file, your open request succeeds unless all other processes have specified "Deny" mode or "Deny write." Macro Definition: open_handle macro path,access mov dx, offset path mov al, access mov ah, 3DH int 21H endm Example: The following program prints a file named textfile.asc that is on the disk in drive B. file db "b:textfile.asc",0 buffer db ? handle dw ? ; begin: open_handle file,0 ; THIS FUNCTION mov handle,ax ; Save handle read_char: read_handle handle,buffer,1 ; Read 1 character jc error_read ; Routine not shown cmp ax,0 ; End of file? je return ; Yes, go home print_char buffer ; See Function 05H jmp read_char ; Read another ──────────────────────────────────────────────────────────────────────────── Close Handle (Function 3EH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 3EH BX Handle Return: Carry set: AX 6 = Invalid handle Carry not set: No error Comments: Function 3EH closes a file opened with Function 3DH (Open Handle) or 3CH (Create Handle). BX must contain the handle of the open file that you want to close. If there is no error, MS-DOS closes the file and flushes all internal buffers. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 6 Handle not open or invalid ────────────────────────────────────────────────────────────────────────── Macro Definition: close_handle macro handle mov bx,handle mov ah,3EH int 21H endm Example: The following program creates a file named dir.tmp, containing the filename and extension of each file in the current directory, in the current directory on the disk in drive B. srch_file db "b:*.*",0 tmp_file db "b:dir.tmp",0 buffer db 43 dup (?) handle dw ? ; begin: set_dta buffer ; See Function 1AH find_first_file srch_file,16H ; See Function 4EH cmp ax,12H ; Directory empty? je all_done ; Yes, go home create_handle tmp_file,0 ; See Function 3CH jc error_create ; Routine not shown mov handle,ax ; Save handle write_it: write_handle handle,buffer[1EH],12 ; See Function jc error_write ; 40H find_next_file ; See Function 4FH cmp ax,12H ; Another entry? je all_done ; No, go home jmp write_it ; Yes, write record all_done: close_handle handle ; See Function 3EH jc error_close ; Routine not shown ──────────────────────────────────────────────────────────────────────────── Read Handle (Function 3FH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 3FH BX Handle CX Bytes to read DS:DX Pointer to buffer Return: Carry set: AX 5 = Access denied 6 = Invalid handle Carry not set: AX Bytes read Comments: Function 3FH reads from the file or device associated with the specified handle. BX must contain the handle. CX must contain the number of bytes to be read. DX must contain the offset (to the segment address in DS) of the buffer. If there is no error, AX returns the number of bytes read; if you attempt to read starting at end of file, AX returns 0. The number of bytes specified in CX is not necessarily transferred to the buffer; if you use this call to read from the keyboard, for example, it reads only up to the first carriage-return. If you use this function request to read from standard input, you can redirect the input. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 5 Handle not open for reading 6 Handle not open or invalid ────────────────────────────────────────────────────────────────────────── Macro Definition: read_handle macro handle,buffer,bytes mov bx,handle mov dx,offset buffer mov cx,bytes mov ah,3FH int 21H endm Example: The following program displays a file named textfile.asc that is on the disk in drive B. filename db "b:\textfile.asc",0 buffer db 129 dup (?) handle dw ? ; begin: open_handle filename,0 ; See Function 3DH jc error_open ; Routine not shown mov handle,ax ; Save handle read_file: read_handle buffer,file_handle,128 jc error_open ; Routine not shown cmp ax,0 ; End of file? je return ; Yes, go home mov bx,ax ; # of bytes read mov buffer[bx],"$" ; Make a string display buffer ; See Function 09H jmp read_file ; Read more ──────────────────────────────────────────────────────────────────────────── Write Handle (Function 40H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 40H BX Handle CX Bytes to write DS:DX Pointer to buffer Return: Carry set: AX 5 = Access denied 6 = Invalid handle Carry not set: AX Bytes written Comments: Function 40H writes to the file or device associated with the specified handle. BX must contain the handle. CX must contain the number of bytes to be written. DX must contain the offset (to the segment address in DS) of the data to be written. If you set CX to zero, the file will be truncated at the current position of the file pointer. MS-DOS will not perform the write if the handle is read-only. If there is no error, AX returns the number of bytes written. Be sure to check AX after performing a write. If its value is less than the number in CX when the call was made, it indicates an error, even though the carry flag isn't set. If AX contains 0, and if the target is a disk file, the disk is full. If you use this function request to write to standard output, you can redirect the output. If you call this request with CX=0, the file size is set to the value of the read/write pointer. To satisfy the new file size, allocation units are allocated or released, as required. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 5 Handle not open for writing 6 Handle not open or invalid ────────────────────────────────────────────────────────────────────────── Macro Definition: write_handle macro handle,buffer,bytes mov bx,handle mov dx,offset buffer mov cx,bytes mov ah,40H int 21H endm Example: The following program creates a file named dir.tmp, containing the filename and extension of each file in the current directory, in the current directory on the disk in drive B. srch_file db "b:*.*",0 tmp_file db "b:dir.tmp",0 buffer db 43 dup (?) handle dw ? ; begin: set_dta buffer ; See Function 1AH find_first_file srch_file,16H ; Check directory cmp ax,12H ; Directory empty? je return ; Yes, go home create_handle tmp_file,0 ; See Function 3CH jc error_create ; Routine not shown mov handle,ax ; Save handle write_it: write_handle handle,buffer[1EH],12 ; THIS FUNCTION jc error_write ; Routine not shown find_next_file ; Check directory cmp ax,12H ; Another entry? je all_done ; No, go home jmp write_it ; Yes, write record all_done: close_handle handle ; See Function 3EH jc error_close ; Routine not shown ──────────────────────────────────────────────────────────────────────────── Delete Directory Entry [Unlink] (Function 41H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 41H DS:DX Pointer to pathname Return: Carry set: AX 2 = File not found 3 = Path not found 5 = Access denied Carry not set: No error Comments: Function 41H erases a file by deleting its directory entry. DX must contain the offset (from the segment address in DS) of an ASCIZ string that specifies the pathname of the file that you want to delete. You cannot use wildcard characters. If the file exists and is not read-only, the call deletes it. If there is an error, the call sets the carry flag (CF) and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 2 File doesn't exist, or specifies a directory 3 Path is invalid 5 File is read-only ────────────────────────────────────────────────────────────────────────── To delete a file with the read-only attribute, first change its attribute to 0 with Function 43H (Get/Set File Attributes). Macro Definition: delete_entry macro path mov dx,offset path mov ah,41H int 21H endm Example: The following program deletes all files, dated before December 31, 1986, from the disk in drive B. year db 1986 month db 12 day db 31 files db ? message db "NO FILES DELETED.",0DH,0AH,"$" path db "b:*.*", 0 buffer db 43 dup (?) ; begin: set_dta buffer ; See Function 1AH select_disk "B" ; See Function 0EH find_first_file path,0 ; See Function 4EH jnc compare ; got one jmp all_done ; no match, go home compare: convert_date buffer[-1] ; See end of chapter cmp cx,year ; After 1986? jg next ; Yes, don't delete cmp dl,month ; After December? jg next ; Yes, don't delete cmp dh,day ; 31st or after? jge next ; Yes, don't delete delete_entry buffer[1EH] ; THIS FUNCTION jc error_delete ; Routine not shown inc files ; Bump file counter next: find_next_file ; Check directory jnc compare ; Go home if done how_many: cmp files,0 ; Was directory empty? je all_done ; Yes, go home convert files,10,message ; See end of chapter all_done: display message ; See Function 09H select_disk "A" ; See Function 0EH ──────────────────────────────────────────────────────────────────────────── Move File Pointer (Function 42H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 42H AL Method of moving BX Handle CX:DX Distance in bytes (offset) Return: Carry set: AX 1 = Invalid function 6 = Invalid handle Carry not set: DX:AX New read/write pointer location Comments: Function 42H moves the read/write pointer of the file associated with the specified handle. BX must contain the handle. CX and DX must contain a 32-bit offset (CX contains the most significant byte). AL must contain a code that specifies how to move the pointer: Code Cursor Moved to ────────────────────────────────────────────────────────────────────────── 0 Beginning of file plus the offset 1 Current pointer location plus the offset 2 End of file plus the offset ────────────────────────────────────────────────────────────────────────── DX and AX return the new location of the read/write pointer (a 32-bit integer; DX contains the most significant byte). You can determine the length of a file by setting CX:DX to 0, AL to 2, and calling this function. DX:AX returns the offset of the byte following the last byte in the file (size of the file in bytes). If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 AL not 0, 1, or 2 6 Handle not open ────────────────────────────────────────────────────────────────────────── Macro Definition: move_ptr macro handle,high,low,method mov bx,handle mov cx,high mov dx,low mov al,method mov ah,42H int 21H endm Example: The following program prompts for a letter, converts it to its alphabetic sequence (A=1, B=2, etc.), then reads and displays the corresponding record from the file named alphabet.dat that is in the current directory on the disk in drive B. The file contains 26 records, each 28 bytes long. file db "b:alphabet.dat",0 buffer db 28 dup (?),"$" prompt db "Enter letter: $" crlf db 0DH,0AH,"$" handle db ? record_length dw 28 ; begin: open_handle file,0 ; See Function 3DH jc error_open ; Routine not shown mov handle,ax ; Save handle get_char: display prompt ; See Function 09H read_kbd_and_echo ; See Function 01H sub al,41h ; Convert to sequence mul byte ptr record_length ; Calculate offset move_ptr handle,0,ax,0 ; THIS FUNCTION jc error_move ; Routine not shown read_handle handle,buffer,record_length jc error_read ; Routine not shown cmp ax,0 ; End of file? je return ; Yes, go home display crlf ; See Function 09H display buffer ; See Function 09H display crlf ; See Function 09H jmp get_char ; Get another character ──────────────────────────────────────────────────────────────────────────── Get/Set File Attributes (Function 43H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 43H AL 0 = Get attributes 1 = Set attributes CX (if AL=1) Attributes to be set DS:DX Pointer to pathname Return: Carry set: AX 1 = Invalid function 2 = File not found 3 = Path not found 5 = Access denied Carry not set: CX Attribute byte (if AL=0) Comments: Function 43H gets or sets the attributes of a file. DX must contain the offset (from the segment address in DS) of an ASCIZ string that specifies the pathname of a file. AL must specify whether to get or set the attribute (0=get, 1=set). If AL is 0 (get the attribute), the attribute byte returns in CX. If AL is 1 (set the attribute), CX must contain the attributes to be set. See Section 1.5.5, "File Attributes," for a description of the attributes. You cannot change the VolumeID bit (08H) or the Subdirectory bit (10H) of the attribute byte with this function. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 AL not 0 or 1 2 File doesn't exist 3 Path invalid 5 Attribute in CX cannot be changed (Subdirectory or ────────────────────────────────────────────────────────────────────────── Macro Definition: change_attr macro path,action,attrib mov dx,offset path mov al,action mov cx,attrib mov ah,43H int 21H endm Example: The following program displays the attributes assigned to the file named report.asm that is in the current directory on the disk in drive B. header db 15 dup (20h),"Read-",0DH,0AH db "Filename Only Hidden " db "System Volume Sub-Dir Archive" db 0DH,0AH,0DH,0AH,"$" path db "b:report.asm",3 dup (0),"$" attribute dw ? blanks db 9 dup (20h),"$" ; begin: change_attr path,0,0 ; THIS FUNCTION jc error_mode ; Routine not shown mov attribute,cx ; Save attribute byte display header ; See Function 09H display path ; See Function 09H mov cx,6 ; Check 6 bits (0-5) mov bx,1 ; Start with bit 0 chk_bit: test attribute,bx ; Is the bit set? jz no_attr ; No display_char "X" ; See Function 02H jmp short next_bit ; Done with this bit no_attr: display_char 20h ; See Function 02H next_bit: display blanks ; See Function 09H shl bx,1 ; Move to next bit loop chk_bit ; Check it ──────────────────────────────────────────────────────────────────────────── IOCtl Data (Function 44H, Codes 0 and 1) ──────────────────────────────────────────────────────────────────────────── Call: AH = 44H AL 0 = Get device data 1 = Set device data BX Handle DX Device data (see text) Return: Carry set: AX 1 = Invalid function 6 = Invalid handle Carry not set: DX Device data Comments: Function 44H, Codes 0 and 1, either gets or sets the data MS-DOS uses to control the device. AL must contain 0 to get the data or 1 to set it. BX must contain the handle. If AL is 1, DH must contain 0. The device-data word is specified or returned in DX. If bit 7 of the data is 1, the handle refers to a device and the other bits have the meanings shown in Table 1.23. Table 1.23 MS-DOS Data Bit Values ╓┌─┌──────────┌────────────────────┌─────────────────────────────────────────╖ Bit Value Meaning ────────────────────────────────────────────────────────────────────────── Bit Value Meaning ────────────────────────────────────────────────────────────────────────── 0 1 Console input device 1 1 Console output device 2 1 Null device 3 1 Clock device 4 1 Reserved 5 1 Don't check for control characters 0 Check for control characters 6 0 End of file on input 8-10 Reserved 11 1 Device understands open/close Bit Value Meaning ────────────────────────────────────────────────────────────────────────── 11 1 Device understands open/close 12 Reserved 13 1 Device supports output until busy 14 1 Device can process control strings sent with Functions 4402H and 4403H (IOCtl character); bit can be read only, but not set 15 Reserved ────────────────────────────────────────────────────────────────────────── You must set the reserved bits to zero. The control characters referred to in the description of bit 5 are CONTROL+C, CONTROL+P, CONTROL+S, and CONTROL+Z. To read these characters as data, instead of as control characters, you must set bit 5 and use either Function 33H, CONTROL+C Check, or the MS-DOS break command to turn off CONTROL+C checking. If bit 7 of DX is 0, the handle refers to a file and the other bits have the following meanings: Bit Value Meaning ────────────────────────────────────────────────────────────────────────── 0-5 Drive number (0=A, 1=B, etc.) 6 0 The file has been written 8-15 Reserved ────────────────────────────────────────────────────────────────────────── If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 AL not 0 or 1, or AL is 1 but DH is not 0 6 Handle in BX not open or is invalid ────────────────────────────────────────────────────────────────────────── Macro Definition: ioctl_data macro code,handle mov bx,handle mov al,code mov ah,44H int 21H endm Example: The following program gets the device data for standard output, sets the bit that specifies not to check for control characters (bit 5), and then clears the bit. get equ 0 set equ 1 stdout equ 1 ; begin: ioctl_data get,stdout ; THIS FUNCTION jc error ; routine not shown mov dh,0 ; clear DH or dl,20H ; set bit 5 ioctl_data set,stdout ; THIS FUNCTION jc error ; routine not shown ; ; <control characters now treated as data, or "raw mode"> ; ioctl_data get,stdout ; THIS FUNCTION jc error ; routine not shown mov dh,0 ; clear DH and dl,0DFH ; clear bit 5 ioctl_data set,stdout ; THIS FUNCTION ; ; <control characters now interpreted, or "cooked mode"> ; ──────────────────────────────────────────────────────────────────────────── IOCtl Character (Function 44H, Codes 2 and 3) ──────────────────────────────────────────────────────────────────────────── Call: AH = 44H AL 2 = Send control data 3 = Receive control data BX Handle CX Bytes to read or write DS:DX Pointer to buffer Return: Carry set: AX 1 = Invalid function 6 = Invalid handle Carry not set: AX Bytes transferred Comments: Function 44H, Codes 2 and 3, sends or receives control data to or from a character device. AL must contain 2 to send data or 3 to receive. BX must contain the handle of a character device, such as a printer or serial port. CX must contain the number of bytes to be read or written. DX must contain the offset (to the segment address in DS) of the data buffer. AX returns the number of bytes transferred. The device driver must support the IOCtl interface. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 AL not 2 or 3, or device cannot perform the specified function 6 Handle in BX not open or doesn't exist ────────────────────────────────────────────────────────────────────────── Macro Definition: ioctl_char macro code,handle,buffer mov bx,handle mov dx,offset buffer mov al,code mov ah,44H int 21H endm Example: No general example is applicable, since processing of IOCtl control data depends on the device being used, as well as the device driver. ──────────────────────────────────────────────────────────────────────────── IOCtl Block (Function 44H, Codes 4 and 5) ──────────────────────────────────────────────────────────────────────────── Call: AH = 44H AL 4 = Send control data 5 = Receive control data BL Drive number (0=default, 1=A, etc.) CX Bytes to read or write DS:DX Pointer to buffer Return: Carry set: AX 1 = Invalid function 5 = Invalid drive Carry not set: AX Bytes transferred Comments: Function 44H, Codes 4 and 5, sends or receives control data to or from a block device. AL must contain 4 to send data or 5 to receive. BL must contain the drive number (0=default, 1=A, etc.). CX must contain the number of bytes to be read or written. DX must contain the offset (to the segment address in DS) of the data buffer. AX returns the number of bytes transferred. The device driver must support the IOCtl interface. To determine whether or not it does, use Function 4400H to get the device data, and test bit 14; if the bit is set, the driver supports IOCtl. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 AL not 4 or 5, or device cannot perform the specified function 5 Number in BL not a valid drive number ────────────────────────────────────────────────────────────────────────── Macro Definition: ioctl_status macro code,drive,buffer mov bl,drive mov dx,offset buffer mov al,code mov ah,44H int 21H endm Example: No general example is applicable, since processing of IOCtl control data depends on the device being used, as well as the device driver. ──────────────────────────────────────────────────────────────────────────── IOCtl Status (Function 44H, Codes 6 and 7) ──────────────────────────────────────────────────────────────────────────── Call: AH = 44H AL 6 = Check input status 7 = Check output status BX Handle Return: Carry set: AX 1 = Invalid function 5 = Access denied 6 = Invalid handle 13 = Invalid data Carry not set: AL 00H = Not ready 0FFH = Ready Comments: Function 44H, Codes 6 and 7, checks whether or not the file or device associated with a handle is ready. AL must contain 6 to check whether the handle is ready for input or 7 to check whether the handle is ready for output. BX must contain the handle. AL returns the status: Meaning for Meaning for Meaning for Value Device Input File Output File ────────────────────────────────────────────────────────────────────────── 00H Not ready Pointer is at EOF Ready 0FFH Ready Ready Ready ────────────────────────────────────────────────────────────────────────── An output file always returns ready, even if the disk is full. bp If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 AL not 6 or 7 5 Access denied 6 Number in BX not a valid, open handle 13 Invalid data ────────────────────────────────────────────────────────────────────────── Macro Definition: ioctl_status macro code,handle mov bx,handle mov al,code mov ah,44H int 21H endm Example: The following program displays a message that tells whether the file associated with handle 6 is ready for input or whether it is at end-of-file. stdout equ 1 ; message db "File is " ready db "ready." at_eof db "at EOF." crlf db ODH,OAH ; begin: write_handle stdout,message,8 ; display message jc write_error ; routine not shown ioctl_status 6 ; THIS FUNCTION jc ioctl_error ; routine not shown cmp al,0 ; check status code jne not_eof ; file is ready write_handle stdout,at_eof,7 ; see Function 40H jc write_error ; routine not shown jmp all_done ; clean up & go home not_eof: write_handle stdout,ready,6 ; see Function 40H all_done: write_handle stdout,crlf,2 ; see Function 40H jc write_error ; routine not shown ──────────────────────────────────────────────────────────────────────────── IOCtl Is Changeable (Function 44H, Code 08H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 44H AL = 08H BL Drive number (0=default, 1=A, etc.) Return: Carry set: AX 1 = Invalid function 15 = Invalid drive Carry not set: AX 0 = Changeable 1 = Not changeable Comments: Function 44H, Code 08H, checks whether a drive contains a removable or nonremovable disk. BL must contain the drive number (0=default, 1=A, etc.). AX returns 0 if the disk can be changed, 1 if it cannot. This call lets a program determine whether or not to issue a message to change disks. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 Device does not support this call 15 Number in BL not a valid drive number ────────────────────────────────────────────────────────────────────────── When the call returns error 1 (because the driver doesn't support it), the caller assumes that the driver cannot be changed. Macro Definition: ioctl_change macro drive mov bl, drive mov al, 08H mov ah, 44H int 21H endm Example: The following program checks whether or not the current drive contains a removable disk. If not, processing continues; if so, the program prompts the user to replace the disk in the current drive. stdout equ 1 ; message db "Please replace disk in drive " drives db "ABCD" crlf db 0DH,0AH ; begin: ioctl_change 0 ; THIS FUNCTION jc ioctl_error ; routine not shown cmp ax,0 ; current drive changeable? jne continue ; no, continue processing write_handle stdout,message,29 ; see Function 40H jc write_error ; routine not shown current_disk ; see Function 19H xor bx,bx ; clear index mov bl,al ; get current drive display_char drives[bx] ; see Function 02H write_handle stdout,crlf,2 ; see Function 40H jc write_error ; routine not shown continue: ; (Further processing here) ──────────────────────────────────────────────────────────────────────────── IOCtl Is Redirected Block (Function 44H, Code 09H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 44H AL = 09H BL Drive number (0=default, 1=A, etc.) Return: Carry set: AX 1 = Invalid function code 15 = Invalid drive number Carry not set: DX Device-attribute bits Comments: Function 44H, Code 09H, checks whether a drive letter refers to a drive on a Microsoft Networks workstation (local) or is redirected to a server (remote). BL must contain the drive number (0=default, 1=A, etc.). If the block device is local, DX returns the attribute word from the device header. If the block device is remote, only bit 12 (1000H) is set; the other bits are 0 (reserved). An application program should not test bit 12, because applications should not make distinctions between local and remote files (or devices). Programs should be written so that they will be independent of the location of a device that has been removed. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 File sharing must be loaded to use this system call 15 Number in BL not a valid drive number ────────────────────────────────────────────────────────────────────────── Macro Definition: ioctl_rblock macro drive mov bl, drive mov al, 09H mov ah, 44H int 21H endm Example: The following program checks whether or not drive B is local or remote and displays the appropriate message. stdout equ 1 ; message db "Drive B: is " loc db "local." rem db "remote." crlf db 0DH,0AH ; begin: write_handle stdout,message,12 ; display message jc write_error ; routine not shown ioctl_rblock 2 ; THIS FUNCTION jc ioctl_error ; routine not shown test dx,1000h ; bit 12 set? jnz not_loc ; yes, it's remote write_handle stdout,loc,6 ; see Function 40H jc write_error ; routine not shown jmp done not_loc: write_handle stdout,rem,7 ; see Function 40H jc write_error ; routine not shown done: write_handle stdout,crlf,2 ; see Function 40H jc write_error ; routine not shown ──────────────────────────────────────────────────────────────────────────── IOCtl Is Redirected Handle (Function 44H, Code 0AH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 44H AL = 0AH BX Handle Return: Carry set: AX 1 = Invalid function code 6 = Invalid handle Carry not set: DX IOCtl bit field Comments: Function 44H, Code 0AH, checks whether a handle refers to a file or a device on a Microsoft Networks workstation (local) or is redirected to a server (remote). BX must contain the file handle. DX returns the IOCtl bit field; bit 15 is set if the handle refers to a remote file or device. An application program should not test bit 15, because applications should not make distinctions between local and remote files (or devices). Programs should be written so that they will be independent of the location of a device that has been removed. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 Network must be loaded to use this system call 6 Handle in BX not a valid, open handle ────────────────────────────────────────────────────────────────────────── Macro Definition: ioctl_rhandle macro handle mov bx, handle mov al, 0AH mov ah, 44H int 21H endm Example: The following program checks whether handle 5 refers to a local or remote file or a device and displays the appropriate message. stdout equ 1 ; message db "Handle 5 is " loc db "local." rem db "remote." crlf db 0DH,0AH ; begin: write_handle stdout,message,12; display message jc write_error ; routine not shown ioctl_rhandle 5 ; THIS FUNCTION jc ioctl_error ; routine not shown test dx,8000h ; bit 15 set? jnz not_loc ; yes, it's remote write_handle stdout,loc,6 ; see Function 40H jc write_error ; routine not shown jmp done not_loc: write_handle stdout,rem,7 ; see Function 40H jc write_error ; routine not shown done: write_handle stdout,crlf,2 ; see Function 40H jc write_error ; routine not shown ──────────────────────────────────────────────────────────────────────────── IOCtl Retry (Function 44H, Code 0BH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 44H AL = 0BH DX Number of retries CX Wait time Return: Carry set: AX 1 = Invalid function code Carry not set: No error Comments: Function 44H, Code 0BH, specifies how many times MS-DOS should retry a disk operation that fails because of a file-sharing violation. DX must contain the number of retries. CX controls the pause between retries. MS-DOS retries this type of disk operation three times, unless you use this system call to specify a different number. After the specified number of retries, MS-DOS issues Interrupt 24H (Critical-Error-Handler Address) for the requesting process. The effect of the delay parameter in CX is machine-dependent because it specifies how many times MS-DOS should execute an empty loop. The actual time varies, depending on the processor and clock speed. You can determine the effect on your machine by using debug. Set the number of retries to 1 and then time several values of CX. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 File sharing must be loaded to use this system call ────────────────────────────────────────────────────────────────────────── Macro Definition: ioctl_retry macro retries, wait mov dx, retries mov cx, wait mov al, 0BH mov ah, 44H int 21H endm Example: The following program sets the number of sharing retries to 10 and specifies a delay of 1000 between retries. begin: ioctl_retry 10,1000 ; THIS FUNCTION jc error ; routine not shown ──────────────────────────────────────────────────────────────────────────── Generic IOCtl (for Handles) (Function 44H, Code 0CH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 44H AL = 0CH BX Handle CH = 05H Category code (printer device) CL Function (minor) code DS:DX Pointer to data buffer Return: Carry set: AX 1 = Invalid function code -- = Any device error Carry not set: No error Comments: This call loads and selects code pages for devices on a per-device basis. It also sets or gets the output iteration count for a printer that supports "PRINT 'TIL BUSY." The video functions (type=display) are supported only if ansi.sys has been installed. If ansi.sys is not installed, mode sets the video state directly. This information reflects the latest mode command or any changes made by use of BIOS. This call uses BIO to get and set the states. The MS-DOS 4.0 mode command sets the values through this interface and the DOS utilities access the information through this interface. The category code may be one of the following: Code Meaning ────────────────────────────────────────────────────────────────────────── 00 Unknown device 01 Serial printer 03 Console (display) device 05 Parallel printer ────────────────────────────────────────────────────────────────────────── The function code may be one of the following: Code Meaning ────────────────────────────────────────────────────────────────────────── 45H Sets iteration count for printer 4AH Selects code page 4CH Starts prepare list 4DH Ends prepare list 5FH Sets display device 65H Gets iteration count for printer 6AH Query code page selected 6BH Query code page prepare list 7FH Gets display character (screen width, length, and color) ────────────────────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────────────────── Note DS:DX points to a word that contains the new value for the total number of output iterations performed before proceeding. Thus, DS:DX points to a word that contains the character iteration count for the "PRINT 'TIL BUSY" loop. This is the number of times the device driver will wait for the device to signal "ready" before acknowledging "Device busy." ────────────────────────────────────────────────────────────────────────── Macro Definition: ioctl_handles macro handle,function,category,buffer mov ch,05H mov cl,function mov dx,offset buffer mov bx,handle mov ah,44H mov al,0CH int 21H endm Example: The following program obtains device characteristics. mov ax,440CH ; Handle based generic IOCTL mov bx,handle ; Handle of open device mov ch,03H ; Type = display mov cl,7FH ; Subfunction for get lds dx,buffer ; Info buffer int 21H jc error buffer label byte ; Return buffer db 0 ; Info level (set to 0 ; before call) db 0 ; reserved (") ; for type display dw 7*2 ; length of data dw flags ; control flags ; 0001H=intense (vs blink) ; display mode ; 1=text ; 2=APA db 0 ; reserved dw colors ; # of colors (monochrome=0) dw width ; width of display (pixels) dw length ; length of display (pixels) dw cols ; width of display (chars) dw rows ; length of display (lines) To fetch code-page information, return the DBCS range vector and add the following: mov ax=440Ch ; Handle generic IOCTL mov cx,036AH ; Query display mov bx,handle lds dx,buffer ; change buffer content int 21H jc error Buffer Label Word dw end-start ; length start: dw codepage ; code page db s1,e1 ; DBCS range db 0,0 ; end of list ────────────────────────────────────────────────────────────────────────── Note Some device drivers may only support the codepage value. As a result, the user of this call must check the returned length before assuming the DBCS information is present. The display.sys and printer.sys device drivers do not need to support the DBCS information. Only the drivers supplied with the Asian MS-DOS 4.0 will provide this support. ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Generic IOCtl (for Devices) (Function 44H, Code 0DH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 44H AL = 0DH BL Drive number (0 = default, 1 = A, etc.) CH = 08H Category (major) code CL Function (minor) code DS:DX Pointer to parameter block -1 Return: Carry set: AX 1 = Invalid function code 2 = Invalid drive - = Any device error Carry not set: No error Comments: The function code may be one of the following: Code Meaning ────────────────────────────────────────────────────────────────────────── 40 Set device parameters 41 Write track on logical device 42 Format track on logical device 60 Get device parameters 61 Read track on logical device 62 Verify track on logical device ────────────────────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────────────────── Note You must issue "Set Parameters Device" before you can read, write, format, or verify a logical drive. ────────────────────────────────────────────────────────────────────────── You should use the following procedure when you want to read, write, format, or verify a logical drive: 1. Save drive parameters using "Get Device Parameters." 2. Set desired drive parameters using "Set Device Parameters." 3. Perform the I/O operation. 4. Restore the original drive parameters using "Set Device Parameters." Set Device Parameters (Function 440DH, CL=40H) When CL=40H, the parameter block has the following field format: ┌────────────────────────────────────┐ │ BYTE Special Functions │ ├────────────────────────────────────┤ │ BYTE Device Type │ ├────────────────────────────────────┤ │ WORD Device Attributes │ ├────────────────────────────────────┤ │ WORD Number of Cylinders │ ├────────────────────────────────────┤ │ BYTE Media Type │ ├────────────────────────────────────┤ │ Device BPB │ ├────────────────────────────────────┤ │ Track Layout │ └────────────────────────────────────┘ These fields have the following meanings: Special Functions ╓┌─┌──────────┌─────────┌────────────────────────────────────────────────────╖ Bit Value Meaning ────────────────────────────────────────────────────────────────────────── Bit Value Meaning ────────────────────────────────────────────────────────────────────────── 0 0 The Device BPB (BIOS Parameter Block) field contains the new default BPB for this device. If a previous Set Device Parameters call set this bit, Build BPB returns the actual media BPB otherwise, it returns the default BPB for the device. 1 All subsequent Build BPB requests return the device BPB. 1 0 Read all fields of the parameter block. 1 Ignore all fields of the parameter block except for the Track Layout field. 2 0 The sectors in the track may not all be the same size. (You should not use this setting.) 1 The sectors in the track are all the same size and the sector numbers range between 1 and the total Bit Value Meaning ────────────────────────────────────────────────────────────────────────── the sector numbers range between 1 and the total number of sectors actually in the track. You should always set this bit. 3-7 0 These bits must be zero. ────────────────────────────────────────────────────────────────────────── Device Type This byte describes the physical device and is set by the device. When set, it has the following meanings: Value Meaning ────────────────────────────────────────────────────────────────────────── 0 320/360kilobytes 1 1.2 megabytes 2 720 kilobytes 3 8-inch, single-density 4 8-inch, double-density 5 Hard disk 6 Tape drive 7 1.44 megabytes ────────────────────────────────────────────────────────────────────────── Device Attributes Bit Value Meaning ────────────────────────────────────────────────────────────────────────── 0 The media is removable. 0 1 The media is not removable. 1 0 Disk change-line is not supported (no door lock support). 1 Disk change-line is supported (door lock support). 2-7 0 These bits must be zero. ────────────────────────────────────────────────────────────────────────── Number of Cylinders This field indicates the maximum number of cylinders that the physical device can support. This information is set by the device. Media Type For drives that may contain different media, this field (which is device-dependent) indicates which media the drive expects. For a 1.2-megabyte disk, bit zero has the following meaning: Bit Value Meaning ────────────────────────────────────────────────────────────────────────── 0 0 Quad-density, 1.2-megabyte disk 1 Double-density, 320/360-kilobyte disk ────────────────────────────────────────────────────────────────────────── The default media type is a quad-density, 1.2-megabyte disk. Device BPB If bit 0 of the Special Functions field is clear, the BPB in this field is the new default BPB for the device. If bit 0 of the Special Functions field is set, the device driver returns the BPB from this field for subsequent Build BPB requests. Track Layout This field contains a table of variable length for each logical device and indicates the expected layout of the sectors on the media track. The field has the following format: ┌──────────────────────────────────────────────┐ │ WORD Sector Count -- total # of sectors │ ├──────────────────────────────────────────────┤ │ WORD Sector Number -- sector #1 │ ├──────────────────────────────────────────────┤ │ WORD Sector Size -- sector #1 │ ├──────────────────────────────────────────────┤ │ WORD Sector Number -- sector #2 │ ├──────────────────────────────────────────────┤ │ WORD Sector Size -- sector #2 │ └──────────────────────────────────────────────┘ . . . ┌──────────────────────────────────────────────┐ │ WORD Sector Number -- sector #n │ ├──────────────────────────────────────────────│ │ WORD Sector Size -- sector #n │ └──────────────────────────────────────────────┘ The Sector Count field indicates the total number of sectors. Each sector number must be unique and in the range of 1 to sector count (n). If bit 2 of the Special Functions field is set, all sector sizes must be the same. Get Device Parameters (Function 440DH, CL=60H) When CL=60H, the parameter block has the same field layout as for CL=40H. However, some of the fields have different meanings. These are described as follows: Special Functions Bit Value Meaning ────────────────────────────────────────────────────────────────────────── 0 0 Returns the default BPB for the device. 1 Returns the BPB that Build BPB would return. 1-7 0 These bits must be zero. ────────────────────────────────────────────────────────────────────────── Track Layout The Get Device Parameters call does not use this field. Read/Write Track on Logical Drive (Function 440DH, CL=61H/CL=41H) To write to a track on a logical drive, set CL=41H. To read a track on a logical drive, set CL=61H. When CL=41H or 61H, the parameter block has the following format: ┌──────────────────────────────┐ │ BYTE Special Functions │ ├──────────────────────────────┤ │ WORD Head │ ├──────────────────────────────┤ │ WORD Cylinder │ ├──────────────────────────────┤ │ WORD First Sector │ ├──────────────────────────────┤ │ WORD Number of Sectors │ ├──────────────────────────────│ │ DWORD Transfer Address │ └──────────────────────────────┘ These fields are described as follows: Special Functions This byte must be zero. Head This field contains the number of the head on which you perform the write or read. Cylinder This field contains the number of the cylinder on which you perform the write or read. First Sector This field contains the number of the first sector on which you perform the write or read. Sectors are numbered starting with zero, so the fourth sector is numbered 3. Number of Sectors This field contains the total number of sectors. Transfer Address This field contains the address for storing the data to be written or the data just read. Format/Verify Track on Logical Drive (Function 440DH, CL=42H/CL=62H) To format and verify a track on a logical drive, set CL=42H. To verify a track on a logical drive, set CL=62H. When CL=42H or 62H, the parameter block has the following format: ┌──────────────────────────────┐ │ BYTE Special Functions │ ├──────────────────────────────┤ │ WORD Head │ │──────────────────────────────┤ │ WORD Cylinder │ └──────────────────────────────┘ These fields are described as follows: Special Functions This byte must be zero. Head This field contains the number of the head on which you perform the format or verify. Cylinder This field contains the number of the cylinder on which you perform the format or verify. ──────────────────────────────────────────────────────────────────────────── Get/Set IOCtl Drive Map (Function 44H, Codes 0EH and 0FH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 44H AL OEH = Get logical drive map OFH = Set logical drive map BX Drive number (0 = default, 1 = A, etc.) Return: Carry set: AX 1 = Invalid function code 5 = Invalid drive Carry not set: AL = Logical drive mapped onto physical drive (= 0 if only one drive is assigned to this physical drive) Comments: MS-DOS supports the mapping of multiple logical drives onto a single physical block device. Get IOCtl Drive Map lets you query the DOS about which logical drive is currently mapped onto the corresponding physical device. Set IOCtl Drive Map alters the device that is currently mapped onto the physical device. These functions are only useful if there is more than one logical block device mapped onto a single physical device. A possible use for these functions is with applications that want to disable the DOS prompt in order to place the correct floppy disk in the drive when accessing the other logical drive. To detect whether or not a logical device currently owns the physical device to which it is mapped, a program needs to check the value in AL after calling Function 440EH or 440FH (Get/Set IOCtl Drive Map). ──────────────────────────────────────────────────────────────────────────── Duplicate File Handle (Function 45H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 45H BX Handle Return: Carry set: AX 4 = Too many open files 6 = Invalid handle Carry not set: AX New handle Comments: Function 45H creates an additional handle for a file. BX must contain the handle of an open file. MS-DOS returns the new handle in AX. The new handle refers to the same file as the handle in BX, with the file pointer at the same position. After you use this function request, moving the read/write pointer of either handle also moves the pointer for the other handle. You usually use this function request to redirect standard input (handle 0) and standard output (handle 1). For a description of standard input, standard output, and the advantages and techniques of manipulating them, see Software Tools by Brian W. Kernighan and P.J. Plauger (Addison-Wesley Publishing Co., 1976). If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 4 Too many open files (no handle available) 6 Handle not open or is invalid ────────────────────────────────────────────────────────────────────────── Macro Definition: xdup macro handle mov bx,handle mov ah,45H int 21H endm Example: The following program redirects standard output (handle 1) to a file named dirfile, invokes a second copy of command.com to list the directory (which writes the directory to dirfile), and then restores standard input to handle 1. pgm_file db "command.com",0 cmd_line db 9,"/c dir /w",0dH parm_blk db 14 dup (0) path db "dirfile",0 dir_file dw ? ; For handle sav_stdout dw ? ; For handle ; begin: set_block last_inst ; See Function 4AH jc error_setblk ; Routine not shown create_handle path,0 ; See Function 3CH jc error_create ; Routine not shown mov dir_file,ax ; Save handle xdup 1 ; THIS FUNCTION jc error_xdup ; Routine not shown mov sav_stdout,ax ; Save handle xdup2 dir_file,1 ; See Function 46H jc error_xdup2 ; Routine not shown exec pgm_file,cmd_line,parm_blk ; See Function 4BH jc error_exec ; Routine not shown xdup2 sav_stdout,1 ; See Function 46H jc error_xdup2 ; Routine not shown close_handle sav_stdout ; See Function 3EH jc error_close ; Routine not shown close_handle dir_file ; See Function 3EH jc error_close ; Routine not shown ──────────────────────────────────────────────────────────────────────────── Force Duplicate File Handle (Function 46H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 46H BX Handle CX Second handle Return: Carry set: AX 4 = Too many open files 6 = Invalid handle Carry not set: No error Comments: Function 46H forces a specified handle to refer to the same file as a second handle already associated with an open file. BX must contain the handle of the open file; CX must contain the second handle. On return, the handle in CX now refers to the same file at the same position as the handle in BX. If the file referred to by the handle in CX was open at the time of the call, this function closes it. After you use this call, moving the read/write pointer of either handle also moves the pointer for the other handle. Normally, you would use this function request to redirect standard input (handle 0) and standard output (handle 1). For a description of standard input, standard output, and the advantages and techniques of manipulating them, see Software Tools by Brian W. Kernighan and P.J. Plauger (Addison-Wesley Publishing Co., 1976). If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 4 Too many open files (no handle available) 6 Handle not open or is invalid ────────────────────────────────────────────────────────────────────────── Macro Definition: xdup2 macro handle1,handle2 mov bx,handle1 mov cx,handle2 mov ah,46H int 21H endm Example: The following program redirects standard output (handle 1) to a file named dirfile, invokes a second copy of command.com to list the directory (which writes the directory to dirfile), and then restores standard input to handle 1. pgm_file db "command.com",0 cmd_line db 9,"/c dir /w",0dH parm_blk db 14 dup (0) path db "dirfile",0 dir_file dw ? ; For handle sav_stdout dw ? ; For handle ; begin: set_block last_inst ; See Function 4AH jc error_setblk ; Routine not shown create_handle path,0 ; See Function 3CH jc error_create ; Routine not shown mov dir_file,ax ; Save handle xdup 1 ; See Function 45H jc error_xdup ; Routine not shown mov sav_stdout,ax ; Save handle xdup2 dir_file,1 ; jc error_xdup2 ; Routine not shown exec pgm_file,cmd_line,parm_blk ; See Function 4BH jc error_exec ; Routine not shown xdup2 sav_stdout,1 ; THIS FUNCTION jc error_xdup2 ; Routine not shown close_handle sav_stdout ; See Function 3EH jc error_close ; Routine not shown close_handle dir_file ; See Function 3EH jc error_close ; Routine not shown ──────────────────────────────────────────────────────────────────────────── Get Current Directory (Function 47H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 47H DS:SI Pointer to 64-byte memory area DL Drive number (0 = default, 1 = A, etc.) Return: Carry set: AX 15 = Invalid drive number Carry not set: No error Comments: Function 47H returns the pathname of the current directory on a specified drive. DL must contain a drive number (0=default, 1=A, etc.). SI must contain the offset (from the segment address in DS) of a 64-byte memory area. MS-DOS places an ASCIZ string in the memory area, consisting of the path (starting from the root directory) of the current directory for the drive specified in DL. The string does not begin with a backslash and does not include the drive letter. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 15 Number in DL not a valid drive number ────────────────────────────────────────────────────────────────────────── Macro Definition: get_dir macro drive,buffer mov dl,drive mov si,offset buffer mov ah,47H int 21H endm Example: The following program displays the current directory that is on the disk in drive B. disk db "b:\#" buffer db 64 dup (?) ; begin: get_dir 2,buffer ; THIS FUNCTION jc error_dir ; Routine not shown display disk ; See Function 09H display_asciz buffer ; See end of chapter ──────────────────────────────────────────────────────────────────────────── Allocate Memory (Function 48H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 48H BX Paragraphs of memory requested Return: Carry set: AX 7 = Memory-control blocks damaged 8 = Insufficient memory BX Paragraphs of memory available Carry not set: AX Segment address of allocated memory Comments: Function 48H tries to allocate the specified amount of memory to the current process. BX must contain the number of paragraphs of memory (one paragraph is 16 bytes). If sufficient memory is available to satisfy the request, AX returns the segment address of the allocated memory (the offset is 0). If sufficient memory is not available, BX returns the number of paragraphs of memory in the largest available block. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 7 Memory-control blocks damaged (a user program changed memory that didn't belong to it) 8 Not enough free memory to satisfy the request ────────────────────────────────────────────────────────────────────────── Macro Definition: allocate_memory macro bytes mov bx,bytes mov cl,4 shr bx,cl inc bx mov ah,48H int 21H endm Example: The following program opens the file named textfile.asc, calculates its size with Function 42H (Move File Pointer), allocates a block of memory the size of the file, reads the file into the allocated memory block, and then frees the allocated memory. path db "textfile.asc",0 msg1 db "File loaded into allocated memory block.", 0DH,0AH msg2 db "Allocated memory now being freed (deallocated).",0DH,0AH handle dw ? mem_seg dw ? file_len dw ? ; begin: open_handle path,0 jc error_open ; Routine not shown mov handle,ax ; Save handle move_ptr handle,0,0,2 ; See Function 42H jc error_move ; Routine not shown mov file_len,ax ; Save file length set_block last_inst ; See Function 4AH jc error_setblk ; Routine not shown allocate_memory file_len ; THIS FUNCTION jc error_alloc ; Routine not shown mov mem_seg,ax ; Save address of new memory move_ptr handle,0,0,0 ; See Function 42H jc error_move ; Routine not shown push ds ; Save DS mov ax,mem_seg ; Get segment of new memory mov ds,ax ; Point DS at new memory read_handle cs:handle,0,cs:file_len ; Read file into ; new memory pop ds ; Restore DS jc error_read ; Routine not shown ; (CODE TO PROCESS FILE GOES HERE) write_handle stdout,msg1,42 ; See Function 40H jc write_error ; Routine not shown free_memory mem_seg ; See Function 49H jc error_freemem ; Routine not shown write_handle stdout,msg2,49 ; See Function 40H jc write_error ; Routine not shown ──────────────────────────────────────────────────────────────────────────── Free Allocated Memory (Function 49H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 49H ES Segment address of memory to be freed Return: Carry set: AX 7 = Memory-control blocks damaged 9 = Incorrect segment Carry not set: No error Comments: Function 49H frees (makes available) a block of memory previously allocated with Function 48H (Allocate Memory). ES must contain the segment address of the memory block to be freed. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 7 Memory-control blocks damaged (a user program changed memory that didn't belong to it) 9 Memory pointed to by ES was not allocated with Function 48H ────────────────────────────────────────────────────────────────────────── Macro Definition: free_memory macro seg_addr mov ax,seg_addr mov es,ax mov ah,49H int 21H endm Example: The following program opens a file named textfile.asc, calculates its size with Function 42H (Move File Pointer), allocates a block of memory the size of the file, reads the file into the allocated memory block, and then frees the allocated memory. path db "textfile.asc",0 msg1 db "File loaded into allocated memory block.", 0DH,0AH msg2 db "Allocated memory now being freed (deallocated).",0DH,0AH handle dw ? mem_seg dw ? file_len dw ? ; begin: open_handle path,0 jc error_open ; Routine not shown mov handle,ax ; Save handle move_ptr handle,0,0,2 ; See Function 42H jc error_move ; Routine not shown mov file_len,ax ; Save file length set_block last_inst ; See Function 4AH jc error_setblk ; Routine not shown allocate_memory file_len ; See Function 48H jc error_alloc ; Routine not shown mov mem_seg,ax ; Save address of new memory mov_ptr handle,0,0,0 ; See Function 42H jc error_move ; Routine not shown push ds ; Save DS mov ax,mem_seg ; Get segment of new memory mov ds,ax ; Point DS at new memory read_handle handle,code,file_len ; Read file into ; new memory pop ds ; Restore DS jc error_read ; Routine not shown ; (CODE TO PROCESS FILE GOES HERE) write_handle stdout,msg1,42 ; See Function 40H jc write_error ; Routine not shown free_memory mem_seg ; THIS FUNCTION jc error_freemem ; Routine not shown write_handle stdout,msg2,49 ; See Function 40H jc write_error ; Routine not shown ──────────────────────────────────────────────────────────────────────────── Set Block (Function 4AH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 4AH BX Paragraphs of memory ES Segment address of memory area Return: Carry set: AX 7 = Memory-control blocks damaged 8 = Insufficient memory 9 = Incorrect segment BX Paragraphs of memory available Carry not set: No error Comments: Function 4AH changes the size of a memory-allocation block. ES must contain the segment address of the memory block. BX must contain the new size of the memory block, in paragraphs (one paragraph is 16 bytes). MS-DOS attempts to change the size of the memory block. If the call fails on a request to increase memory, BX returns the maximum size (in paragraphs) to which the block can be increased. Since MS-DOS allocates all available memory to a .com program, you would use this call most often to reduce the size of a program's initial memory-allocation block. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 7 Memory-control blocks destroyed (a user program changed memory that didn't belong to it) 8 Not enough free memory to satisfy the request 9 Wrong address in ES (the memory block it points to ────────────────────────────────────────────────────────────────────────── The following macro shrinks the initial memory-allocation block of a .com program. It takes as a parameter the offset of the first byte following the last instruction of a program (LAST_INST in the sample programs), uses it to calculate the number of paragraphs in the program, and then adds 17 to the result: one to round up and 16 to set aside 256 bytes for a stack. It then sets up SP and BP to point to this stack. Macro Definition: set_block macro last_byte mov bx,offset last_byte mov cl,4 shr bx,cl add bx,17 mov ah,4AH int 21H mov ax,bx shl ax,cl dec ax mov sp,ax mov bp,sp endm Example: The following program invokes a second copy of command.com and executes a dir (directory) command. pgm_file db "command.com",0 cmd_line db 9,"/c dir /w",0DH parm_blk db 14 dup (?) reg_save db 10 dup (?) ; begin: set_block last_inst ; THIS FUNCTION exec pgm_file,cmd_line,parm_blk,0 ; See Function 4BH ──────────────────────────────────────────────────────────────────────────── Load and Execute Program (Function 4BH, Code 00H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 4BH AL = 00H DS:DX Pointer to pathname ES:BX Pointer to parameter block Return: Carry set: AX 1 = Invalid function 2 = File not found 3 = Path not found 4 = Too many open files 5 = Access denied 8 = Insufficient memory 10 = Bad environment 11 = Bad format Carry not set: No error Comments: Function 4BH, Code 00H, loads and executes a program. DX must contain the offset (from the segment address in DS) of an ASCIZ string that specifies the drive and pathname of an executable program file. BX must contain the offset (from the segment address in ES) of a parameter block. AL must contain 0. There must be enough free memory for MS-DOS to load the program file. MS-DOS allocates all available memory to a program when it loads it, so you must free some memory with Function 4AH (Set Block) before using this function request to load and execute another program. Unless you or MS-DOS needs the memory for some other purpose, you should shrink the memory to the minimum amount required by the current process before issuing this request. MS-DOS creates a Program Segment Prefix for the program being loaded and sets the terminate and CONTROL+C addresses to the instruction that immediately follows the call to Function 4BH in the invoking program. The parameter block consists of four addresses: Table 1.24 Contents of the Parameter Block Offset Length (Hex) (Bytes) Description ────────────────────────────────────────────────────────────────────────── 00 2 (word) Segment address of the environment to be passed; 00H means copy the parent program's environment 02 4 (dword) Segment: Offset of command line to be placed at offset 80H of the new Program Segment Prefix. Must be a correctly formed command line no longer than 128 bytes 06 4 (dword) Segment: Offset of FCB to be placed at offset 5CH of the new Program Segment Prefix (the Program Segment Prefix is described in Chapter 4, "MS-DOS Control Blocks and Work Areas") 0A 4 (dword) Segment: Offset of FCB to be placed at offset 6CH of the new Program Segment ────────────────────────────────────────────────────────────────────────── All open files of a program are available to the newly loaded program, giving the parent program control over the definition of standard input, output, auxiliary, and printer devices. For example, a program could write a series of records to a file, open the file as standard input, open a second file as standard output, and then use Function 4BH, Code 00H, (Load and Execute Program) to load and execute a program that takes its input from standard input, sorts records, and writes to standard output. The loaded program also receives an environment, a series of ASCIZ strings of the form parameter=value (for example, verify= on). The environment must begin on a paragraph boundary, be less than 32 kilobytes long, and end with a byte of 00H (that is, the final entry consists of an ASCIZ string followed by two bytes of 00H). Following the last byte of zeros is a set of initial arguments passed to a program containing a word count followed by an ASCIZ string. If the call finds the file in the current directory, the ASCIZ string contains the drive and pathname of the executable program as passed to Function 4BH. If the call finds the file in the path, it concatenates the filename with the path information. (A program may use this area to determine from where it was loaded.) If the word-environment address is 0, the loaded program either inherits a copy of the parent program's environment or receives a new environment built for it by the parent. Place the segment address of the environment at offset 2CH of the new Program Segment Prefix. To build an environment for the loaded program, put it on a paragraph boundary and place the segment address of the environment in the first word of the parameter block. To pass a copy of the parent's environment to the loaded program, put 00H in the first word of the parameter block. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 AL not 0 or 3 2 Program file not found 3 Path invalid or not found 4 Too many open files (no handle available) 5 Directory full, a directory with the same name exists, or a file with the same name exists 8 Not enough memory to load the program 10 Environment appears longer than 32 kilobytes 11 Program file is a .exe file that contains internally ────────────────────────────────────────────────────────────────────────── Executing Another Copy of Command.com Since command.com builds pathnames, searches command paths for program files, and relocates .exe files, the simplest way to load and execute another 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. This action requires 17 kilobytes of available memory, so a program that does it should be sure to shrink its initial memory-allocation block with Function 4AH (Set Block). The following is the format of a command line that contains the /c switch: length,/c command,0DH where: Length is the length of the command line, counting the length byte but not the ending carriage-return (0DH). Command is any valid MS-DOS command. 0DH is a carriage-return character. If a program executes another program directly──naming it as the program file to Function 4BH instead of command.com──it must perform all the processing normally done by command.com. Macro Definition: exec macro path,command,parms mov dx,offset path mov bx,offset parms mov word ptr parms[02H],offset command mov word ptr parms[04H],cs mov word ptr parms[06H],5CH mov word ptr parms[08H],es mov word ptr parms[0AH],6CH mov word ptr parms[0CH],es mov al,0 mov ah,4BH int 21H endm Example: The following program invokes a second copy of command.com and executes a dir (directory) command by using the /w (wide) switch: pgm_file db "command.com",0 cmd_line db 9,"/c dir /w",0DH parm_blk db 14 dup (?) reg_save db 10 dup (?) ; begin: set_block last_inst ; See Function 4AH exec pgm_file,cmd_line,parm_blk,0 ; THIS FUNCTION ──────────────────────────────────────────────────────────────────────────── Load Overlay (Function 4BH, Code 03H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 4BH AL = 03H DS:DX Pointer to pathname ES:BX Pointer to parameter block Return: Carry set: AX 1 = Invalid function 2 = File not found 3 = Path not found 4 = Too many open files 5 = Access denied 8 = Insufficient memory 10 = Bad environment Carry not set: No error Comments: Function 4BH, Code 03H, loads a program segment (overlay). DX must contain the offset (from the segment address in DS) of an ASCIZ string that specifies the drive and pathname of the program file. BX must contain the offset (from the segment address in ES) of a parameter block. AL must contain 3. MS-DOS assumes that since the invoking program is loading into its own address space, it requires no free memory. This call does not create a Program Segment Prefix. The parameter block is four bytes long: Table 1.25 Contents of the Parameter Block Offset Length (Hex) (Bytes) Description ────────────────────────────────────────────────────────────────────────── 00 2 (word) Segment address at which program is to be loaded 02 2 (word) Relocation factor; usually the same as the first word of the parameter block (for a description of a .exe file and of relocation, see Chapter 6, ".Exe File ────────────────────────────────────────────────────────────────────────── If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 AL not 00H or 03H 2 Program file not found 3 Path invalid or not found 4 Too many open files (no handle available) 5 Directory is full, a directory with the same name exists, or a file with the same name exists 8 Not enough memory to load the program 10 Environment appears longer than 32 kilobytes ────────────────────────────────────────────────────────────────────────── Macro Definition: exec_ovl macro path,parms,seg_addr mov dx,offset path mov bx,offset parms mov parms,seg_addr mov parms[02H],seg_addr mov al,3 mov ah,4BH int 21H endm Example: The following program opens a file named textfile.asc, redirects standard input to that file, loads more.com as an overlay, and calls an overlay named bit.com, which reads textfile.asc as standard input. The overlay must establish its own addressability and end with a FAR return. stdin equ 0 ; file db "TEXTFILE.ASC",0 cmd_file db "\bit.com",0 parm_blk dw 4 dup (?) overlay label dword dw 0 handle dw ? new_mem dw ? ; begin: set_block last_inst ; see Function 4AH jc setblock_error ; routine not shown allocate_memory 2000 ; see Function 48H jc allocate_error ; routine not shown mov new_mem,ax ; save seg of memory open_handle file,0 ; see Function 3DH jc open_error ; routine not shown mov handle,ax ; save handle xdup2 handle,stdin ; see Function 45H jc dup2_error ; routine not shown close_handle handle ; see Function 3EH jc close_error ; routine not shown mov ax,new_mem ; addr of new memory exec_ovl cmd_file,parm_blk,ax ; THIS FUNCTION jc exec_error ; routine not shown call overlay ; call the overlay free_memory new_mem ; see Function 49H jc free_error ; routine not shown ; ──────────────────────────────────────────────────────────────────────────── End Process (Function 4CH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 4CH AL Return code Return: None Comments: Function 4CH terminates a process and returns to MS-DOS. AL contains a return code that can be retrieved by the parent process with Function 4DH (Get Return Code of Child Process) or the if command, using errorlevel. MS-DOS closes all open handles, ends the current process, and returns control to the invoking process. This function request doesn't require CS to contain the segment address of the Program Segment Prefix. You should use it to end a program (rather than Interrupt 20H or a jump to location 0) unless your program must be compatible with MS-DOS versions earlier than 2.0. ────────────────────────────────────────────────────────────────────────── Note If you use file sharing, you must remove all locks issued by this process or DOS will be in an uncertain state. ────────────────────────────────────────────────────────────────────────── Macro Definition: end_process macro return_code mov al,return_code mov ah,4CH int 21H endm Example: The following program displays a message and returns to MS-DOS with a return code of 8. It uses only the opening portion of the sample program skeleton shown at the beginning of this chapter. message db "Displayed by FUNC_4CH example",0DH,0AH,"$" ; begin: display message ; See Function 09H end_process 8 ; THIS FUNCTION code ends end code ──────────────────────────────────────────────────────────────────────────── Get Return Code of Child Process (Function 4DH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 4DH Return: AX Return code Comments: Function 4DH retrieves the return code specified when a child process terminates via either Function 31H (Keep Process) or Function 4CH (End Process). The code returns in AL. AH returns a code that specifies why the program ended: Code Meaning ────────────────────────────────────────────────────────────────────────── 0 Normal termination 1 Terminated by CONTROL+C 2 Critical device error 3 Function 31H (Keep Process) ────────────────────────────────────────────────────────────────────────── This call can retrieve the exit code only once. Macro Definition: ret_code macro mov ah,4DH int 21H endm Example: No example is included for this function request because the meaning of a return code varies. ──────────────────────────────────────────────────────────────────────────── Find First File (Function 4EH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 4EH DS:DX Pointer to pathname CX Attributes to match Return: Carry set: AX 2 = File not found 3 = Path not found 18 = No more files Carry not set: No error Comments: Function 4EH searches the current or specified directory for the first entry that matches the specified pathname. DX must contain the offset (from the segment address in DS) of an ASCIZ string that specifies the pathname, which can contain wildcard characters. CX must contain the attribute to be used in searching for the file, as described in Section 1.5.5, "File Attributes." If the attribute field is hidden file, system file, or subdirectory entry (02H, 04H, or 10H), or any combination of these values, all normal file entries are also searched. To search all directory entries except the volume label, set the attribute byte to 16H (hidden file, system file, and directory entry). If this function finds a directory entry that matches the name and attribute, it fills the current DTA as follows: Table 1.26 DTA Values After Successful Find First File Offset Length Description ────────────────────────────────────────────────────────────────────────── 00H 21 Reserved for subsequent Function 4FH (Find Next File) 15H 1 Attribute found 16H 2 Time file was last written 18H 2 Date file was last written 1AH 2 Low word of file size 1CH 2 High word of file size 1EH 13 Name and extension of the file, followed by 00H. All blanks are removed; if there is an extension, it is preceded by a period. (Volume labels include a period ────────────────────────────────────────────────────────────────────────── If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 2 Specified file invalid or doesn't exist 3 Specified path invalid or doesn't exist 18 No matching directory entry found ────────────────────────────────────────────────────────────────────────── Macro Definition: find_first_file macro path,attrib mov dx,offset path mov cx,attrib mov ah,4EH int 21H endm Example: The following program displays a message that specifies whether a file named report.asm exists in the current directory on the disk in drive B. yes db "File exists.",0DH,0AH,"$" no db "File does not exist.",0DH,0AH,"$" path db "b:report.asm",0 buffer db 43 dup (?) ; begin: set_dta buffer ; See Function 1AH find_first_file path,0 ; THIS FUNCTION jc error_findfirst ; Routine not shown cmp al,12H ; File found? je not_there ; No display yes ; See Function 09H jmp return ; All done not_there: display no ; See Function 09H ──────────────────────────────────────────────────────────────────────────── Find Next File (Function 4FH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 4FH Return: Carry set: AX 18 = No more files Carry not set: No error Comments: Function 4FH searches for the next directory entry that matches the name and attributes specified in a previous Function 4EH (Find First File). The current DTA must contain the information filled in by Function 4EH (Find First File). If the function finds a matching entry, it fills the current DTA just as it did for Find First File (see Function 4EH (Find First File)). If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 2 Specified path invalid or doesn't exist 18 No matching directory entry found ────────────────────────────────────────────────────────────────────────── Macro Definition: find_next_file macro mov ah,4FH int 21H endm Example: The following program displays the number of files contained in the current directory on the disk in drive B. message db "No files",0DH,0AH,"$" files dw ? path db "b:*.*",0 buffer db 43 dup (?) ; begin: set_dta buffer ; See Function 1AH find_first_file path,0 ; See Function 4EH jc error_findfirst ; Routine not shown cmp al,12H ; Directory empty? je all_done ; Yes, go home inc files ; No, bump file counter search_dir: find_next_file ; THIS FUNCTION jc error_findnext ; Routine not shown cmp al,12H ; Any more entries? je done ; No, go home inc files ; Yes, bump file counter jmp search_dir ; And check again done: convert files,10,message ; See end of chapter all_done: display message ; See Function 09H ──────────────────────────────────────────────────────────────────────────── Get Verify State (Function 54H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 54H Return: AL 0 = No verify after write 1 = Verify after write Comments: Function 54H checks whether MS-DOS verifies write operations to disk files. The status returns in AL: 0 if verify is off, 1 if verify is on. You can set the verify status with Function 2EH (Set/Reset Verify Flag). Macro Definition: get_verify macro mov ah,54H int 21H endm Example: The following program displays the verify status: message db "Verify ","$" on db "on.",0DH,0AH,"$" off db "off.",0DH,0AH,"$" ; begin: display message ; See Function 09H get_verify ; THIS FUNCTION cmp al,0 ; Is flag off? jg ver_on ; No, it's on display off ; See Function 09H jmp return ; Go home ver_on: display on ; See Function 09H ──────────────────────────────────────────────────────────────────────────── Change Directory Entry (Function 56H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 56H DS:DX Pointer to pathname ES:DI Pointer to second pathname Return: Carry set: AX 2 = File not found 3 = Path not found 5 = Access denied 17 = Not same device Carry not set: No error Comments: Function 56H renames a file by changing its directory entry. DX must contain the offset (from the segment address in DS) of an ASCIZ string that contains the pathname of the entry to be changed. DI must contain the offset (from the segment address in ES) of an ASCIZ string that contains a second pathname to which the first is to be changed. If a directory entry for the first pathname exists, it is changed to the second pathname. The directory paths need not be the same; in effect, you can move the file to another directory by renaming it. You cannot use this function request to copy a file to another drive, however; if the second pathname specifies a drive, the first pathname must specify or default to the same drive. You cannot use this function request to rename an open file, a hidden file, a system file, or a subdirectory, because it may corrupt your disk. If there is an error, the carry flag (CF) is set and the error code returns in AX. Code Meaning ────────────────────────────────────────────────────────────────────────── 2 One of files is invalid or not open 3 One of paths is invalid or not open 5 First pathname specifies a directory, second pathname specifies an existing file; or second directory entry could not be opened 17 Both files not on the same drive ────────────────────────────────────────────────────────────────────────── Macro Definition: rename_file macro old_path,new_path mov dx,offset old_path push ds pop es mov di,offset new_path mov ah,56H int 21H endm Example: The following program prompts for the name of a file and a new name, then renames the file. prompt1 db "Filename: $" prompt2 db "New name: $" old_path db 15,?,15 dup (?) new_path db 15,?,15 dup (?) crlf db 0DH,0AH,"$" ; begin: display prompt1 ; See Function 09H get_string 15,old_path ; See Function 0AH xor bx,bx ; To use BL as index mov bl,old_path[1] ; Get string length mov old_path[bx+2],0 ; Make an ASCIZ string display crlf ; See Function 09H display prompt2 ; See Function 09H get_string 15,new_path ; See Function 0AH xor bx,bx ; To use BL as index mov bl,new_path[1] ; Get string length mov new_path[bx+2],0 ; Make an ASCIZ string display crlf ; See Function 09H rename_file old_path[2],new_path[2]; THIS FUNCTION jc error_rename ; Routine not shown ──────────────────────────────────────────────────────────────────────────── Get/Set Date/Time of File (Function 57H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 57H AL = Function code 0 = Get date and time 1 = Set date and time BX Handle CX (if AL = 1) Time to be set DX (if AL = 1) Date to be set Return: Carry set: AX 1 = Invalid function 6 = Invalid handle Carry not set: CX (if AL = 0) Time file last written DX (if AL = 0) Date file last written Comments: Function 57H gets or sets the time and date when a file was last written. To get the time and date, AL must contain 0; the time and date return in CX and DX. To set the time and date, AL must contain 1; CX and DX must contain the time and date. BX must contain the file handle. The time and date are in the form described in "Fields of the FCB" in Section 1.9.1. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 AL not 0 or 1 6 Handle in BX invalid or not open ────────────────────────────────────────────────────────────────────────── Macro Definition: get_set_date_time macro handle,action,time,date mov bx,handle mov al,action mov cx,word ptr time mov dx,word ptr date mov ah,57H int 21H endm Example: The following program gets the date of a file named report.asm in the current directory on the disk in drive B, increments the day, increments the month and/or year, if necessary, and sets the new date of the file. month db 31,28,31,30,31,30,31,31,30,31,30,31 path db "b:report.asm",0 handle dw ? time db 2 dup (?) date db 2 dup (?) ; begin: open_handle path,0 ; See Function 3DH mov handle,ax ; Save handle get_set_date_time handle,0,time,date ; THIS FUNCTION jc error_time ; Routine not shown mov word ptr time,cx ; Save time mov word ptr date,dx ; Save date convert_date date[-24] ; See end of chapter inc dh ; Increment day xor bx,bx ; To use BL as index mov bl,dl ; Get month cmp dh,month[bx-1] ; Past last day? jle month_ok ; No, go home mov dh,1 ; Yes, set day to 1 inc dl ; Increment month cmp dl,12 ; Is it past December? jle month_ok ; No, go home mov dl,1 ; Yes, set month to 1 inc cx ; Increment year month_ok: pack_date date ; See end of chapter get_set_date_time handle,1,time,date ; THIS FUNCTION jc error_time ; Routine not shown close_handle handle ; See Function 3EH jc error_close ; Routine not shown ──────────────────────────────────────────────────────────────────────────── Get/Set Allocation Strategy (Function 58H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 58H AL 0 = Get strategy 1 = Set strategy BX (AL = 1) 0 = First fit 1 = Best fit 2 = Last fit Return: Carry set: AX 1 = Invalid function code Carry not set: AX (AL = 0) 0 = First fit 1 = Best fit 2 = Last fit Comments: Function 58H gets or sets the strategy that MS-DOS uses to allocate memory when a process requests it. If AL contains 0, the strategy is returned in AX. If AL contains 1, BX must contain the strategy. The three possible strategies are shown in the following table. Table 1.27 Allocation Strategy Value Name Description ────────────────────────────────────────────────────────────────────────── 0 First fit MS-DOS starts searching at the lowest available block and allocates the first block it finds (the allocated memory is the lowest available block). This is the default strategy. 1 Best fit MS-DOS searches each available block and allocates the smallest available block that satisfies the request. 2 Last fit MS-DOS starts searching at the highest available block and allocates the first block it finds (the allocated memory is ────────────────────────────────────────────────────────────────────────── You can use this function request to control how MS-DOS uses its memory resources. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 AL doesn't contain 0 or 1, or BX doesn't contain 0, 1, or 2. ────────────────────────────────────────────────────────────────────────── Macro Definition: alloc_strat macro code,strategy mov bx,strategy mov al,code mov ah,58H int 21H endm Example: The following program displays the memory-allocation strategy in effect, then forces subsequent memory allocations to the top of memory by setting the strategy to last fit (code 2). get equ 0 set equ 1 stdout equ 1 last_fit equ 2 ; first db "First fit ",0DH,0AH best db "Best fit ",0DH,0AH last db "Last fit ",0DH,0AH ; begin: alloc_strat get ; THIS FUNCTION jc alloc_error ; routine not shown mov cl,4 ; multiply code by 16 shl ax,cl ; to calculate offset mov dx,offset first ; point to first msg add dx,ax ; add to base address mov bx,stdout ; handle for write mov cs,16 ; write 16 bytes mov ah,40h ; write handle int 21H ; system call ; jc write_error ; routine not shown alloc_strat set,last_fit ; THIS FUNCTION ; jc alloc_error ; routine not shown ──────────────────────────────────────────────────────────────────────────── Get Extended Error (Function 59H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 59H BX = 00H Return: AX Extended-error code BH Error class (see text) BL Suggested action (see text) CH Locus (see text) CL, DX, SI, DI, DS, ES destroyed Comments: Function 59H retrieves an extended-error code for the preceding system call. Each release of MS-DOS extends the error codes to cover new capabilities. These new codes are mapped to a simpler set of error codes based on MS-DOS Version 2.0, so that existing programs can continue to operate correctly. Notice that this call destroys all registers except CS:IP and SS:SP. A user-written Interrupt 24H (Critical-Error Handler Address) can use Function 59H to get detailed information about the error that caused the interrupt to be issued. The input BX is a version indicator that specifies for what level of error handling the application was written. The current level is 00H. The extended-error code consists of four separate codes in AX, BH, BL, and CH that give as much detail as possible about the error and suggest how the issuing program should respond. BH──Error Class BH returns a code that describes the class of error that occurred: ╓┌─┌──────────────────┌──────────────────────────────────────────────────────╖ Class Description ────────────────────────────────────────────────────────────────────────── 1 Out of a resource, such as storage or channels 2 Not an error, but a temporary situation (such as a locked region in a file) that is expected to end 3 Authorization problem 4 Internal error in system software 5 Hardware failure 6 System software failure not the fault of the active process (could be caused by missing or incorrect configuration files, for example) 7 Application program error 8 File or item not found Class Description ────────────────────────────────────────────────────────────────────────── 9 File or item of invalid format or type, or that is otherwise invalid or unsuitable 10 Interlocked file or item 11 Wrong disk in drive, bad spot on disk, or other problem with storage medium 12 Other error ────────────────────────────────────────────────────────────────────────── BL──Suggested Action BL returns a code that suggests how the issuing program can respond to the error: Action Description ────────────────────────────────────────────────────────────────────────── 1 Retry, then prompt user 2 Retry after a Pause 3 If user entered data such as drive letter or filename, prompt for it again 4 Terminate with cleanup 5 Terminate immediately; system so unhealthy that program should exit as soon as possible without taking time to close files and update indexes 6 Error is informational 7 Prompt user to perform some action, such as changing ────────────────────────────────────────────────────────────────────────── CH──Locus CH returns a code that provides additional information to help locate the area involved in the failure. This code is particularly useful for hardware failures (BH=5). Locus Description ────────────────────────────────────────────────────────────────────────── 1 Unknown 2 Related to random-access block devices, such as a disk drive 3 Related to Network 4 Related to serial-access character devices, such as a printer 5 Related to random-access memory ────────────────────────────────────────────────────────────────────────── Your programs should handle errors by noting the error return from the original system call and then issuing this system call to get the extended-error code. If the program does not recognize the extended-error code, it should respond to the original error code. This system call is available during Interrupt 24H and may be used to return network-related errors. Macro Definition: get_error macro mov ah, 59H int 21H endm Example: Since this function request provides such detailed information, a general example is not practical. User programs can interpret the various codes to determine what sort of messages or prompts should be displayed, what action to take, and whether or not to terminate the program if recovery from the errors isn't possible. ──────────────────────────────────────────────────────────────────────────── Create Temporary File (Function 5AH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 5AH CX Attribute DS:DX Pointer to pathname, followed by a byte of 0, and then by 13 bytes of memory Return: Carry set: AX 2 = File not found 3 = Path not found 4 = Too many open files 5 = Access denied Carry not set: AX Handle Comments: Function 5AH creates a file with a unique name. DX must contain the offset (from the segment address in DS) of an ASCIZ string that specifies a pathname and 13 bytes of memory (to hold the filename). CX must contain the attribute to be assigned to the file, as described in Section 1.5.5, "File Attributes." MS-DOS creates a unique filename and appends it to the pathname pointed to by DS:DX, creates the file and opens it in compatibility mode, then returns the file handle in AX. A program that needs a temporary file should use this function request to avoid name conflicts. When the creating process exits, MS-DOS does not automatically delete a file created with Function 5AH. When you no longer need the file, you should delete it. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 2 File is invalid or doesn't exist 3 Directory pointed to by DS:DX is invalid or doesn't exist 4 Too many open files (no handle available) 5 Access denied ────────────────────────────────────────────────────────────────────────── Macro Definition: create_temp macro pathname,attrib mov cx,attrib mov dx,offset pathname mov ah,5AH int 21H endm Example: The following program creates a temporary file in the directory named \wp\docs, copies a file named textfile.asc that is in the current directory into the temporary file, and then closes both files. stdout equ 1 ; file db "TEXTFILE.ASC",0 path db "\WP\DOCS",0 temp db 13 dup (0) open_msg db " opened.",0DH,0AH crl_msg db " created.",0DH,0AH rd_msg db " read into buffer.",0DH,0AH wr_msg db "Buffer written to " cl_msg db "Files closed.",0DH,0AH crlf db 0DH,0AH handle1 dw ? handle2 dw ? buffer db 512 dup (?) ; begin: open_handle file,0 ; see Function 3DH jc open_error ; routine not shown mov handle1,ax ; save handle write_handle stdout,file,12 ; see Function 40H jc write_error ; routine not shown write_handle stdout,open_msg,10 ; see Function 40H jc write_error ; routine not shown create_temp path,0 ; THIS FUNCTION jc create_error ; routine not shown mov handle2,ax ; save handle write_handle stdout,path,8 ; see Function 40H jc write_error ; routine not shown display_char "" ; see Function 02H write_handle stdout,temp,12 ; see Function 40H jc write_error ; routine not shown write_handle stdout,crl_msg,11 ; See Function 40H jc write_error ; routine not shown read_handle handle1,buffer,512 ; see Function 3FH jc read_error ; routine not shown write_handle stdout,file,12 ; see Function 40H jc write_error ; routine not shown write_handle stdout,rd_msg,20 ; see Function 40H jc write_error ; routine not shown write_handle handle2,buffer,512 ; see Function 40H jc write_error ; routine not shown write_handle stdout,wr_msg,18 ; see Function 40H jc write_error ; routine not shown write_handle stdout,temp,12 ; see Function 40H jc write_error ; routine not shown write_handle stdout,crlf,2 ; see Function 40H jc write_error ; routine not shown close_handle handle1 ; see Function 3EH jc close_error ; routine not shown close_handle handle2 ; see Function 3EH jc close_error ; routine not shown write_handle stdout,cl_msg,15 ; see Function 40H jc write_error ; routine not shown ──────────────────────────────────────────────────────────────────────────── Create New File (Function 5BH) ──────────────────────────────────────────────────────────────────────────── Call: AH = 5BH CX Attribute DS:DX Pointer to pathname Return: Carry set: AX 2 = File not found 3 = Path not found 4 = Too many open files 5 = Access denied 80 = File already exists Carry not set: AX Handle Comments: Function 5BH creates a new file. DX must contain the offset (from the segment address in DS) of an ASCIZ string that specifies a pathname. CX contains the attribute to be assigned to the file, as described in Section 1.5.5, "File Attributes." If there is no existing file with the same filename, MS-DOS creates the file, opens it in compatibility mode, and returns the file handle in AX. This function request fails if the specified file exists, unlike Function 3CH (Create Handle), which, under the same circumstances, truncates the file to a length of 0. In a multitasking system, the existence of a file is used as a semaphore; you can use this system call as a test-and-set semaphore. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 2 File is invalid or doesn't exist 3 Directory pointed to by DS:DX is invalid or doesn't exist 4 No free handles are available in the current process, or internal system tables are full 5 Access denied 80 File with the same specification pointed to by DS:DX ────────────────────────────────────────────────────────────────────────── Macro Definition: create_new macro pathname,attrib mov cx, attrib mov dx, offset pathname mov ah, 5BH int 21H endm Example: The following program attempts to create a new file named report.asm in the current directory. If the file already exists, the program displays an error message and returns to MS-DOS. If the file doesn't exist and there are no other errors, the program saves the handle and continues processing. err_msg db "FILE ALREADY EXISTS",0DH,0AH,"$" path db "report.asm",0 handle dw ? ; begin: create_new path,0 ; THIS FUNCTION jnc continue ; further processing cmp ax,80 ; file already exist? jne error ; routine not shown display err_msg ; see Function 09H jmp return ; return to MS-DOS continue: mov handle,ax ; save handle ; ; (further processing here) ──────────────────────────────────────────────────────────────────────────── Lock (Function 5CH, Code 00H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 5CH AL = 00H BX Handle CX:DX Offset of region to be locked SI:DI Length of region to be locked Return: Carry set: AX 1 = Invalid function code 6 = Invalid handle 33 = Lock violation 36 = Sharing buffer exceeded Carry not set: No error Comments: Function 5CH, Code 00H, denies all access (read or write) by any other process to the specified region of the file. BX must contain the handle of the file that contains the region to be locked. CX:DX (a four-byte integer) must contain the offset in the file of the beginning of the region. SI:DI (a four-byte integer) must contain the length of the region. If another process attempts to use (read or write) a locked region, MS-DOS retries three times; if the retries fail, MS-DOS issues Interrupt 24H for the requesting process. You can change the number of retries with Function 440BH (IOCtl Retry). The locked region can be anywhere in the file. For instance, locking beyond the end of the file is not an error. A region should be locked for only a brief period, so if it is locked for more than ten seconds you should consider it to be an error. Function 45H (Duplicate File Handle) and Function 46H (Force Duplicate File Handle) duplicate access to any locked region. Passing an open file to a child process with Function 4B00H (Load and Execute Program) does not duplicate access to locked regions. ────────────────────────────────────────────────────────────────────────── Warning If a program closes a file that contains a locked region or terminates with an open file that contains a locked region, the result is undefined. ────────────────────────────────────────────────────────────────────────── Programs that might be terminated by Interrupt 23H (CONTROL+C Handler Address) or Interrupt 24H (Critical-Error-Handler Address) should trap these interrupts and unlock any locked regions before exiting. Programs should not rely on being denied access to a locked region. A program can determine the status of a region (locked or unlocked) by attempting to lock the region and examining the error code. If there is an error, the carry flag (CF) is set and the error code is returned in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 File sharing must be loaded to use this function request. 6 The handle in BX is not a valid, open handle. 33 All or part of the specified region is already locked. 36 There is no more room for lock entries in the buffer. Refer to the share command in the MS-DOS User's Reference for information on allocating more lock ────────────────────────────────────────────────────────────────────────── Macro Definition: lock macro handle,start,bytes mov bx, handle mov cx, word ptr start mov dx, word ptr start+2 mov si, word ptr bytes mov di, word ptr bytes+2 mov al, 0 mov ah, 5CH int 21H endm Example: The following program opens a file named finalrpt in "Deny None" mode and locks two portions of it: the first 128 bytes and bytes 1024 through 5119. After some (unspecified) processing, it unlocks the same portions and closes the file. stdout equ 1 ; start1 dd 0 lgth1 dd 128 start2 dd 1023 lgth2 dd 4096 file db "FINALRPT",0 op_msg db " opened.",0DH,0AH 11_msg db "First 128 bytes locked.",0DH,0AH 12_msg db "Bytes 1024-5119 locked.",0DH,0AH u1_msg db "First 128 bytes unlocked.",0DH,0AH u2_msg db "Bytes 1024-5119 unlocked.",0DH,0AH cl_msg db " closed.:,0DH,0AH handle dw ? ; begin: open_handle file,01000010b ; see Function 3DH jc open_error ; routine not shown write_handle stdout,file,8 ; see Function 40H jc write_error ; routine not shown write_handle stdout,op_msg,10 ; see Function 40H jc write_error ; routine not shown mov handle,ax ; save handle lock handle,start1,lgth1 ; THIS FUNCTION jc lock_error ; routine not shown write_handle stdout,11_msg,25 ; see Function 40H jc write_error ; routine not shown lock handle,start2,lgth2 ; THIS FUNCTION jc lock_error ; routine not shown write_handle stdout,12_msg,25 ; see Function 40H jc write_error ; routine not shown ; ; ( Further processing here ) ; unlock handle,start1,lgth1 ; See Function 5C01H jc unlock_error ; routine not shown write_handle stdout,ul_msg,27 ; see Function 40H jc write_error ; routine not shown unlock handle,start2,lgth2 ; See Function 5C01H jc unlock_error ; routine not shown write_handle stdout,u2_msg,27 ; See Function 40H jc write_error ; routine not shown close_handle handle ; See Function 3EH jc close_error ; routine not shown write_handle stdout,file,8 ; see Function 40H jc write_error ; routine not shown write_handle stdout,cl_msg,10 ; see Function 40H jc write_error ; routine not shown ──────────────────────────────────────────────────────────────────────────── Unlock (Function 5CH, Code 01H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 5CH AL = 01H BX Handle CX:DX Offset of area to be unlocked SI:DI Length of area to be unlocked Return: Carry set: AX 1 = Invalid function code 6 = Invalid handle 33 = Lock violation 36 = Sharing buffer exceeded Carry not set: No error Comments: Function 5CH, Code 01H, unlocks a region previously locked by the same process. BX must contain the handle of the file that contains the region to be unlocked. CX:DX (a four-byte integer) must contain the offset in the file of the beginning of the region. SI:DI (a four-byte integer) must contain the length of the region. The offset and length must be exactly the same as the offset and length specified in the previous Function 5C00H (Lock). The description of Function 5C00H (Lock) describes how to use locked regions. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 File sharing must be loaded to use this function request. 6 The handle in BX is not a valid, open handle. 33 The region specified is not identical to one that was previously locked by the same process. 36 There is no more room for lock entries in the buffer. Refer to the share command in the MS-DOS User's Reference for information on allocating more lock ────────────────────────────────────────────────────────────────────────── You should issue Function 59H (Get Extended Error) to list the possible errors returned by this function. Macro Definition: unlock macro handle,start,bytes mov bx, handle mov cx, word ptr start mov dx, word ptr start+2 mov si, word ptr bytes mov di, word ptr bytes+2 mov al, 1 mov ah, 5CH int 21H endm Example: The following program opens a file named finalrpt in "Deny None" mode and locks two portions of it: the first 128 bytes and bytes 1024 through 5119. After some (unspecified) processing, it unlocks the same portions and closes the file. stdout equ 1 ; start1 dd 0 lgth1 dd 128 start2 dd 1023 lgth2 dd 4096 file db "FINALRPT",0 op_msg db " opened.",0DH,0AH 11_msg db "First 128 bytes locked.",0DH,0AH 12_msg db "Bytes 1024-5119 locked.",0DH,0AH u1_msg db "First 128 bytes unlocked.",0DH,0AH u2_msg db "Bytes 1024-5119 unlocked.",0DH,0AH cl_msg db " closed.",0DH,0AH handle dw ? ; begin: open_handle file,01000010b ; see Function 3DH jc open_error ; routine not shown write_handle stdout,file,8 ; see Function 40H jc write_error ; routine not shown write_handle stdout,op_msg,10 ; see Function 40H jc write_error ; routine not shown mov handle,ax ; save handle lock handle,start1,lgth1 ; See Function 5C00H jc lock_error ; routine not shown write_handle stdout,11_msg,25 ; see Function 40H jc write_error ; routine not shown lock handle,start2,lgth2 ; See Function 5C00H jc lock_error ; routine not shown write_handle stdout,12_msg,25 ; see Function 40H jc write_error ; routine not shown ; ; ( Further processing here ) ; unlock handle,start1,lgth1 ; THIS FUNCTION jc unlock_error ; routine not shown write_handle stdout,u1_msg,27 ; see Function 40H jc write_error ; routine not shown unlock handle,start2,lgth2 ; THIS FUNCTION jc unlock_error ; routine not shown write_handle stdout,u2_msg,27 ; see Function 40H jc write_error ; routine not shown close_handle handle ; See Function 3EH jc close_error ; routine not shown write_handle stdout,file,8 ; see Function 40H jc write_error ; routine not shown write_handle stdout,cl_msg,10 ; see Function 40H jc write_error ; routine not shown ──────────────────────────────────────────────────────────────────────────── Get Machine Name (Function 5EH, Code 00H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 5EH AL = 0 DS:DX Pointer to 16-byte buffer Return: Carry set: AX 1 = Invalid function code Carry not set: CX Identification number of local computer CH Validity of machine name: 00H = invalid nonzero = valid CL NETBIOS number assigned to machine name DS:DX Segment:offset of ASCIZ machine name Comments: Function 5EH, Code 00H, retrieves the net name of the local computer. DX must contain the offset (to the segment address in DS) of a 16-byte buffer. Microsoft Networks must be running. MS-DOS returns the local computer name (a 16-byte ASCIZ string, padded with blanks) in the buffer pointed to by DS:DX. CX returns the identification number of the local computer. If the network was never installed, the CH register returns with zero and the value in the CL register is invalid. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 Microsoft Networks must be running to use this function request. ────────────────────────────────────────────────────────────────────────── Macro Definition: get_machine_name macro buffer mov dx,offset buffer mov al,0 mov ah,5EH int 21H endm Example: The following program displays the name of a Microsoft Networks workstation. stdout equ 1 ; msg db "Netname: " mac_name db 16 dup (?),0DH,0AH ; begin: get_machine_name mac_name ; THIS FUNCTION jc name_error ; routine not shown write_handle stdout,msg,27 ; see Function 40H jc write_error ; routine not shown ──────────────────────────────────────────────────────────────────────────── Get/Set Printer Setup (Function 5EH, Codes 02H and 03H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 5EH AL 02H = Set printer setup string 03H = Get printer setup string BX Assign-list index If AL = 02H CX Length of setup string DS:SI Pointer to setup string If AL = 03H ES:DI = Segment: offset of 64-byte buffer to receive string Return: Carry set: AX 1 = Invalid function code Carry not set: CX = Length of printer setup string in bytes (if AL=03H) ES:DI = Segment:offset of ASCII printer setup string (if AL=03H) Comments: Function 5EH, Code 02H, defines a string of control characters that MS-DOS adds to the beginning of each file sent to the network printer. BX must contain the index into the assign list that identifies the printer (entry 0 is the first entry). CX must contain the length of the string. SI must contain the offset (to the segment address in DS) of the string itself. Microsoft Networks must be running. MS-DOS adds the setup string to the beginning of each file sent to the printer, which is specified by the assign-list index in BX. This function request lets each program that shares a printer have its own printer configuration. You can use Function 5F02H (Get Assign-List Entry) to determine which entry in the assign list refers to the printer. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 Microsoft Networks must be running to use this function request. ────────────────────────────────────────────────────────────────────────── Macro Definition: printer_setup macro index,lgth,string mov bx, index mov cx, lgth mov dx, offset string mov al, 2 mov ah, 5EH int 21H endm Example: The following program defines a printer-setup string that consists of the control character to print expanded type on Epson-compatible printers. The printer cancels this mode at the first carriage return, so the effect is to print the first line of each file sent to the network printer as a title in expanded characters. The setup string is one character. This example assumes that the printer is the entry number 3 (the fourth entry) in the assign list. Use Function 5F02H (Get Assign-List Entry) to determine this value. setup db 0EH ; begin: printer_setup 3,1,setup ; THIS FUNCTION jc error ; routine not shown ──────────────────────────────────────────────────────────────────────────── Get Assign-List Entry (Function 5FH, Code 02H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 5FH AL = 02H BX Assign-list index DS:SI Pointer to buffer for local name ES:DI Pointer to buffer for remote name Return: Carry set: AX 1 = Invalid function code 18 = No more files Carry not set: BL 3 = Printer 4 = Drive CX Stored user value Comments: Function 5FH, Code 02H, retrieves the specified entry from the network list of assignments. BX must contain the assign-list index (entry 0 is the first entry). SI must contain the offset (to the segment address in DS) of a 16-byte buffer for the local name. DI must contain the offset (to the segment address in ES) of a 128-byte buffer for the remote name. Microsoft Networks must be running. MS-DOS puts the local name in the buffer pointed to by DS:SI and the remote name in the buffer pointed to by ES:DI. The local name can be a null ASCIZ string. BL returns 3 if the local device is a printer or 4 if the local device is a drive. CX returns the stored user value set with Function 5F03H (Make Network Connection). The contents of the assign list can change between calls. You can use this function request to retrieve any entry, or to make a copy of the complete list by stepping through the table. To detect the end of the assign list, check for error code 18 (no more files), as you would when stepping through a directory by using Functions 4EH (Find First File) and 4FH (Find Next File). If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 Microsoft Networks must be running to use this function request. 18 The index passed in BX is greater than the number of ────────────────────────────────────────────────────────────────────────── Macro Definition: get_list macro index,local,remote mov bx, index mov si, offset local mov di, offset remote mov al,2 mov ah, 5FH int 21H endm Example: The following program displays the assign list on a Microsoft Networks workstation, showing the local name, remote name, and device type (drive or printer) for each entry. stdout equ 1 printer equ 3 ; local_nm db 16 dup (?),2 dup (20h) remote_nm db 128 dup (?),2 dup (20h) header db "Local name",8 dup (20h) db "Remote name",7 dup (20h) db "Device Type" crlf db 0dh,0ah,0dh,0ah drive_msg db "drive" print_msg db "printer" index dw ? ; begin: write_handle stdout,header,51 ; see Function 40H jc write_error ; routine not shown mov index,0 ; assign list index ck_list: get_list index,local_nm,remote_nm ; THIS FUNCTION jnc got_one ; got an entry error: cmp ax,18 je last_one ; yes jmp error ; routine not shown got_one: push bx ; save device type write_handle stdout,local_nm,148 ; see Function 40H jc write_error ; routine not shown pop bx ; get device type cmp bl,printer ; is it a printer? je prntr ; yes write_handle stdout,drive_msg,5 ; see Function 40H jc write_error ; routine not shown jmp get_next ; finish message prntr: write_handle stdout,print_msg,7 ; see Function 40H jc write_error ; routine not shown get_next: write_handle stdout,crlf,2 ; see Function 40H jc write_error ; routine not shown inc index ; bump index jmp ck_list ; get next entry last_one: write_handle stdout,crlf,4 ; see Function 40H jc write_error ; routine not shown ; ──────────────────────────────────────────────────────────────────────────── Make Network Connection (Function 5FH, Code 03H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 5FH AL = 03H BL 3 = Printer 4 = Drive CX User value DS:SI Pointer to name of source device ES:DI Pointer to name of destination device Return: Carry set: AX 1 = Invalid function code 5 = Access denied 3 = Path not found 8 = Insufficient memory (Other errors particular to the network may occur.) Carry not set: No error Comments: Function 5FH, Code 03H, redirects a printer or disk drive (source device) to a network directory (destination device). BL must contain 3 if the source device is a printer or 4 if it is a disk drive. SI must contain the offset (to the segment address in DS) of an ASCIZ string that specifies the name of the printer, or a drive letter followed by a colon, or a null string (one byte of 00H). DI must contain the offset (to the segment address in ES) of an ASCIZ string that specifies the name of a network directory. CX contains a user-specified 16-bit value that MS-DOS maintains. Microsoft Networks must be running. The destination string must be an ASCIZ string of the following form: machine-name pathname 00H password 00H where: Machine-name is the net name of the server that contains the network directory. Pathname is the alias of the network directory (not the directory path) to which the source device is to be redirected. 00H is a null byte. Password is the password for access to the network directory. If no password is specified, both null bytes must immediately follow the pathname. If BL=3, the source string must be PRN, LPT1, LPT2, or LPT3. This function buffers and sends all output for the named printer to the remote-printer spooler named in the destination string. If BL=4, the source string can be either a drive letter followed by a colon, or a null string. If the source string contains a valid drive letter and colon, this call redirects all subsequent drive-letter references to the network directory named in the destination string. If the source string is a null string, MS-DOS attempts to grant access to the network directory with the specified password. The maximum length of the destination string is 128 bytes. You can retrieve the value in CX by using Function 5F02H (Get Assign-List Entry). If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 Microsoft Networks must be running to use this function request; the value in BX is not 1 to 4, the source string is in the wrong format; the destination string is in the wrong format; or the source device is already redirected. 3 The network directory path is invalid or doesn't exist. 5 The network directory/password combination is not valid. This does not mean that the password itself was invalid; the directory might not exist on the server. 8 There is not enough memory for string substitutions. ────────────────────────────────────────────────────────────────────────── Macro Definition: redir macro device,value,source,destination mov bl, device mov cx, value mov si, offset source mov es, seg destination mov di, offset destination mov al, 03H mov ah, 5FH int 21H endm Example: The following program redirects two drives and a printer from a workstation to a server named harold. It assumes the machine name, directory names, and driver letters shown: Local drive Netname or printer on server Password E: WORD none F: COMM fred PRN: PRINTER quick printer equ 3 drive equ 4 ; local_1 db "e:",0 local_2 db "f:",0 local_3 db "prn",0 remote_1 db "\harold\word",0,0 remote_2 db "\harold\comm",0,"fred",0 remote_3 db "\harold\printer",0,"quick",0 ; begin: redir local_1,remote_1,drive,0 ; THIS FUNCTION jc error ; routine not shown redir local_2,remote_2,drive,0 ; THIS FUNCTION jc error ; routine not shown redir local_3,remote_3,printer,0 ; THIS FUNCTION jc error ; routine not shown ──────────────────────────────────────────────────────────────────────────── Delete Network Connection (Function 5FH, Code 04H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 5FH AL = 04H DS:SI Pointer to name of source device Return: Carry set: AX 1 = Invalid function code 15 = Redirection paused on server (Other errors particular to the network may occur.) Carry not set: No error Comments: Function 5FH, Code 04H, cancels the redirection of a printer or disk drive (source device) to a network directory (destination device) made with Function 5F03H (Make Network Connection). SI must contain the offset (to the segment address in DS) of an ASCIZ string that specifies the name of the printer or drive whose redirection is to be canceled. Microsoft Networks must be running. The ASCIZ string pointed to by DS:SI can contain one of three values: ■ The letter of a redirected drive, followed by a colon. Cancels the redirection and restores the drive to its physical meaning. ■ The name of a redirected printer (PRN, LPT1, LPT2, LPT3, or their machine-specific equivalents). Cancels the redirection and restores the printer name to its physical meaning. ■ A string starting with \\ (2 backslashes). Terminates the connection between the local machine and the network directory. If there is an error, the carry flag (CF) is set and the error code returns in AX: Code Meaning ────────────────────────────────────────────────────────────────────────── 1 Microsoft Networks must be running to use this function request; or the ASCIZ string names a nonexistent source device. 15 Disk or printer redirection on the network server is ────────────────────────────────────────────────────────────────────────── Macro Definition: cancel_redir macro local mov si, offset local mov al, 4 mov ah, 5FH int 21H endm Example: The following program cancels the redirection of drives E and F and the printer (PRN) of a Microsoft Networks workstation. It assumes that these local devices were redirected previously. local_1 db "e:",0 local_2 db "f:",0 local_3 db "prn",0 ; begin: cancel_redir local_1 ; THIS FUNCTION jc error ; routine not shown cancel_redir local_2 ; THIS FUNCTION jc error ; routine not shown cancel_redir local_3 ; THIS FUNCTION jc error ; routine not shown ──────────────────────────────────────────────────────────────────────────── Get PSP (Function 62H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 62H Return: BX Segment address of the Program Segment Prefix of the current process Comments: Function 62H retrieves the segment address of the currently active process (the start of the Program Segment Prefix). The address returns in BX. Macro Definition: get_psp macro mov ah, 62H int 21H endm Example: The following program displays the segment address of its Program Segment Prefix (PSP) in hexadecimal. msg db "PSP segment address: H",0DH,0AH,"$" ; begin: get_psp ; THIS FUNCTION convert bx,16,msg[21] ; see end of chapter display msg ; see Function 09H ──────────────────────────────────────────────────────────────────────────── Get Extended Country Information (Function 65H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 65H AL Function (minor) code BX Code page (-1 = active CON device) CX Amount of data to return DX Country ID for which information is to be returned (-1=default country) ES:DI Address of country information buffer Return: Carry set: 1 = Buffer has been filled 2 = File not found Carry not set: ES:DI = Pointer to country information buffer Comments: Function 65H retrieves standard country information. This information includes country ID, code page, date and time format, currency symbol, separators (for thousands, decimals, data list, date and time) currency format flags, digits in currency, and case-mapping information. The function code passed in AL may be one of the following: Code Description ────────────────────────────────────────────────────────────────────────── 1 Return standard information 2 Return pointer to uppercase table 4 Return pointer to filename uppercase table 6 Return pointer to collating table 7 Selects the Double Byte Character Set (DBCS) ────────────────────────────────────────────────────────────────────────── Only the information for the default country is kept in the kernel. Country-dependent information for all other countries is contained in the country.sys file. The MS-DOS nlsfunc command is used to access the country-dependent information in country.sys using this call. If the country code and code page number do not match, or if either is invalid, error code 2 is returned to AX. If CX is less than 5, error code 1 is returned. If the amount of information requested is greater than the value of CX, only CX bytes are returned and no error is reported. If AL = 1, the buffer is filled with the following information: db 1 ; Information ID dw ? ; Size (<=38) dw ? ; Country ID dw ? ; Code page If AL = 2, the buffer is filled with the following information: db 2 ; Information ID dd ? ; Double-word pointer to uppercase table If AL = 4, the buffer is filled with the following information: db 4 ; Information ID dd ? ; Double-word pointer to filename uppercase table Both of these tables consist of a length field (two bytes) followed by 128 uppercase values for the upper 128 ASCII characters. The following formula is used to compute the address of an uppercase equivalent in the table: Address of outchar = inchar - (256-table──len) = table──start where: Parameter Meaning ────────────────────────────────────────────────────────────────────────── inchar Character to be generated table──len Length of list of uppercase values (two bytes) table──start Starting address of uppercase table outchar Uppercase value for inchar ────────────────────────────────────────────────────────────────────────── If inchar is greater than or equal to (256 - table──len), then there is an uppercase equivalent in the table; otherwise, there is not. If AL = 6, the buffer is filled with the following information: db 6 ; Information ID dd ? ; Double-word pointer to collating sequence The table is 258 bytes long. The first word is the length of the table. The rest of the table is 256 ASCII values in the appropriate order. ──────────────────────────────────────────────────────────────────────────── Get/Set Global Code Page (Function 66H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 66H AL Function (minor) code BX Code page to set (AL = 2) Return: Carry set: AX 02 = File not found 65 = Device not selected Carry not set: No error Comments: Function 66H gets or sets the code page used by the kernel and all devices. If no other code page has been set, this function gets the default code page from DX. If another code page is set, this function retrieves the active code page from BX. The MS-DOS nlsfunc command and country.sys must be on the system if this function is to be used to change the global code page. The function code may be one of the following: Code Description ────────────────────────────────────────────────────────────────────────── 1 Get code page 2 Set code page ────────────────────────────────────────────────────────────────────────── MS-DOS gets the new code page from the country.sys file. Devices must be prepared for code page switching before a code page can be selected. To prepare a device, a device driver that supports code-page switching must be installed by using the device command in the config.sys file. The user must also use the prepare keyword with the MS-DOS mode command to prepare the device for code-page switching. The code page selected must be compatible with the country code specified in the config.sys file. If MS-DOS cannot read country.sys or another specified country information file, error code 02 is returned to AX. ──────────────────────────────────────────────────────────────────────────── Set Handle Count (Function 67H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 67H BX Number of allowed handles Return: Carry set: AX Carry not set: No error Comments: Function 67H increases or decreases the number of files a program can have open at one time. The maximum number of file handles is 64K. If less than 20 are specified, the minimum handle number, 20, is assumed. If this call is used to reduce the number of allowed handles, the new limit does not take affect until any handles above the new limit are closed. The user should use Function 4AH (Set Block) to allocate memory for the extended handle list if BX is greater than 255. The maximum number for the value of the config.sys command files is 255. ──────────────────────────────────────────────────────────────────────────── Commit File (Function 68H) ──────────────────────────────────────────────────────────────────────────── Call: AH = 68H BX File handle Return: Carry set: AX = error Carry not set No error Comments: Function 68H flushes all buffered data for a file without closing it. Using this call is more efficient than using the traditional close-open sequence, and is more effective for network environments. This call makes sure that the disk image of a file is current. ; Macro Definitions for MS-DOS System Call Examples ; ; ******************* ; Interrupts ; ******************* ; Interrupt 25H 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 ; Interrupt 26H 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 ; Interrupt 27H STAY_RESIDENT macro last_instruc mov dx,offset last_instruc inc dx int 27H endm ; ; ; ******************* ; Function Requests ; ******************* ; Function Request 00H TERMINATE_PROGRAM macro xor ah,ah int 21H endm ; Function Request 01H READ_KBD_AND_ECHO macro mov ah,01H int 21H endm ; Function Request 02H DISPLAY_CHAR macro character mov dl,character mov ah,02H int 21H endm ; Function Request 03H AUX_INPUT macro mov ah,03H int 21H endm ; Function Request 04H AUX_OUTPUT macro mov ah,04H int 21H endm ; Function Request 05H PRINT_CHAR macro character mov dl,character mov ah,05H int 21H endm ; Function Request 06H DIR_CONSOLE_IO macro switch mov dl,switch mov ah,06H int 21H endm ; Function Request 07H DIR_CONSOLE_INPUT macro mov ah,07H int 21H endm ; Function Request 08H READ_KBD macro mov ah,08H int 21H endm ; Function Request 09H DISPLAY macro string mov dx,offset string mov ah,09H int 21H endm ; Function Request 0AH GET_STRING macro limit,string mov dx,offset string mov string,limit mov ah,0AH int 21H endm ; Function Request 0BH CHECK_KBD_STATUS macro mov ah,0BH int 21H endm ; Function Request 0CH FLUSH_AND_READ_KBD macro switch mov al,switch mov ah,0CH int 21H endm ; Function Request 0DH RESET_DISK macro mov ah,0DH int 21H endm ; Function Request 0EH SELECT_DISK macro disk mov dl,disk[-65] mov ah,0EH int 21H endm ; Function Request 0FH OPEN macro fcb mov dx,offset fcb mov ah,0FH int 21H endm ; Function Request 10H CLOSE macro fcb mov dx,offset fcb mov ah,10H int 21H endm ; Function Request 11H SEARCH_FIRST macro fcb mov dx,offset fcb mov ah,11H int 21H endm ; Function Request 12H SEARCH_NEXT macro fcb mov dx,offset fcb mov ah,12H int 21H endm ; Function Request 13H DELETE macro fcb mov dx,offset fcb mov ah,13H int 21H endm ; Function Request 14H READ_SEQ macro fcb mov dx,offset fcb mov ah,14H int 21H endm ; Function Request 15H WRITE_SEQ macro fcb mov dx,offset fcb mov ah,15H int 21H endm ; Function Request 16H CREATE macro fcb mov dx,offset fcb mov ah,16H int 21H endm ; Function Request 17H RENAME macro fcb,newname mov dx,offset fcb mov ah,17H int 21H endm ; Function Request 19H CURRENT_DISK macro mov ah,19H int 21H endm ; Function Request 1AH SET_DTA macro buffer mov dx,offset buffer mov ah,1AH endm ; Function Request 1BH DEF_DRIVE_DATA macro mov ah,1BH int 21H endm ; Function Request 1CH DRIVE_DATA macro drive mov dl,drive mov ah,1CH int 21H endm ; Function Request 21H READ_RAN macro fcb mov dx,offset fcb mov ah,21H int 21H endm ; Function Request 22H WRITE_RAN macro fcb mov dx,offset fcb mov ah,22H int 21H endm ; Function Request 23H FILE_SIZE macro fcb mov dx,offset fcb mov ah,23H int 21H endm ; Function Request 24H SET_RELATIVE_RECORD macro fcb mov dx,offset fcb mov ah,24H int 21H endm ; Function Request 25H SET_VECTOR macro interrupt,handler_start mov al,interrupt mov dx,offset handler_start mov ah,25H int 21H endm ; Function Request 26H CREATE_PSP macro seg_addr mov dx,offset seg_addr mov ah,26H int 21H endm ; Function Request 27H RAN_BLOCK_READ macro fcb,count,rec_size mov dx,offset fcb mov cx,count mov word ptr fcb[14],rec_size mov ah,27H int 21H endm ; Function Request 28H RAN_BLOCK_WRITE macro fcb,count,rec_size mov dx,offset fcb mov cx,count mov word ptr fcb[14],rec_size mov ah,28H int 21H endm ; Function Request 29H PARSE macro string,fcb mov si,offset string mov di,offset fcb push es push ds pop es mov al,0FH mov ah,29H int 21H pop es endm ; Function Request 2AH GET_DATE macro mov ah,2AH int 21H endm ; Function Request 2BH SET_DATE macro year,month,day mov cx,year mov dh,month mov dl,day mov ah,2BH int 21H endm ; Function Request 2CH GET_TIME macro mov ah,2CH int 21H endm ; Function Request 2DH SET_TIME macro hour,minutes,seconds,hundredths mov ch,hour mov cl,minutes mov dh,seconds mov dl,hundredths mov ah,2DH int 21H endm ; Function Request 2EH VERIFY macro switch mov al,switch mov ah,2EH int 21H endm ; Function Request 2FH GET_DTA macro mov ah,2FH int 21H endm ; Function Request 30H GET_VERSION macro mov ah,30H int 21H endm ; Function Request 31H KEEP_PROCESS macro return_code,last_byte mov al,return_code mov dx,offset last_byte mov cl,4 shr dx,cl inc dx mov ah,31H int 21H endm ; Function Request 33H CTRL_C_CK macro action,state mov al,action mov dl,state mov ah,33H int 21H endm ; Function Request 35H GET_VECTOR macro interrupt mov al,interrupt mov ah,35H int 21H endm ; Function Request 36H GET_DISK_SPACE macro drive mov dl,drive mov ah,36H int 21H endm ; Function Request 38H GET_COUNTRY macro country,buffer local gc_01 mov dx,offset buffer mov ax,country cmp ax,0FFH jl gc_01 mov al,0ffh mov bx,country gc_01: mov ah,38H int 21H endm ; Function Request 38H SET_COUNTRY macro country local sc_01 mov dx,0FFFFH mov ax,country cmp ax,0FFH jl sc_01 mov al,0ffh mov bx,country sc_01: mov ah,38H int 21H endm ; Function Request 39H MAKE_DIR macro path mov dx,offset path mov ah,39H int 21H endm ; Function Request 3AH REM_DIR macro path mov dx,offset path mov ah,3AH int 21H endm ; Function Request 3BH CHANGE_DIR macro path mov dx,offset path mov ah,3BH int 21H endm ; Function Request 3CH CREATE_HANDLE macro path,attrib mov dx,offset path mov cx,attrib mov ah,3CH int 21H endm ; Function Request 3DH OPEN_HANDLE macro path,access mov dx,offset path mov al,access mov ah,3DH int 21H endm ; Function Request 3EH CLOSE_HANDLE macro handle mov bx,handle mov ah,3EH int 21H endm ; Function Request 3FH READ_HANDLE macro handle,buffer,bytes mov bx,handle mov dx,offset buffer mov cx,bytes mov ah,3FH int 21H endm ; Function Request 40H WRITE_HANDLE macro handle,buffer,bytes mov bx,handle mov dx,offset buffer mov cx,bytes mov ah,40H int 21H endm ; Function Request 41H DELETE_ENTRY macro path mov dx,offset path mov ah,41H int 21H endm ; Function Request 42H MOVE_PTR macro handle,high,low,method mov bx,handle mov cx,high mov dx,low mov al,method mov ah,42H int 21H endm ; Function Request 43H CHANGE_MODE macro path,action,attrib mov dx,offset path mov al,action mov cx,attrib mov ah,43H int 21H endm ; Function Request 4400H,01H IOCTL_DATA macro code,handle mov bx,handle mov al,code mov ah,44H int 21H endm ; Function Request 4402H,03H IOCTL_CHAR macro code,handle,buffer mov bx,handle mov dx,offset buffer mov al,code mov ah,44H int 21H endm ; Function Request 4404H,05H IOCTL_STATUS macro code,drive,buffer mov bl,drive mov dx,offset buffer mov al,code mov ah,44H int 21H endm ; Function Request 4406H,07H IOCTL_STATUS macro code,handle mov bx,handle mov al,code mov ah,44H int 21H endm ; Function Request 4408H IOCTL_CHANGE macro drive mov bl,drive mov al,08H mov ah,44H int 21H endm ; Function Request 4409H IOCTL_RBLOCK macro drive mov bl,drive mov al,09H mov ah,44H int 21H endm ; Function Request 440AH IOCTL_RHANDLE macro handle mov bx,handle mov al,0AH mov ah,44H int 21H endm ; Function Request 440BH IOCTL_RETRY macro retries,wait mov dx,retries mov cx,wait mov al,0BH mov ah,44H int 21H endm ; Function Request 440CH GENERIC_IOCTL_HANDLES macro handle,function,category,buffer mov ch,05H mov cl,function mov dx,offset buffer mov bx,handle mov ah,44H mov al,0CH int 21H endm ; Function Request 440DH GENERIC_IOCTL_BLOCK macro drive_num,function,category,parm_blk mov ch,08H mov cl,function mov dx,offset parm_blk - 1 mov bx,drive_num mov ah,44H mov al,0DH int 21H endm ; Function Request 440EH IOCTL_GET_DRIVE_MAP macro logical_drv mov bx,logical_drv mov ah,44H mov al,0EH int 21H endm ; Function Request 440FH IOCTL_SET_DRIVE_MAP macro logical_drv mov bx,logical_drv mov ah,44H mov al,0FH int 21H endm ; Function Request 45H XDUP macro handle mov bx,handle mov ah,45H int 21H endm ; Function Request 46H XDUP2 macro handle1,handle2 mov bx,handle1 mov cx,handle2 mov ah,46H int 21H endm ; Function Request 47H GET_DIR macro drive,buffer mov dl,drive mov si,offset buffer mov ah,47H int 21H endm ; Function Request 48H ALLOCATE_MEMORY macro bytes mov bx,bytes mov cl,4 shr bx,cl inc bx mov ah,48H int 21H endm ; Function Request 49H FREE_MEMORY macro seg_addr mov ax,seg_addr mov es,ax mov ah,49H int 21H endm ; Function Request 4AH SET_BLOCK macro last_byte mov bx,offset last_byte mov cl,4 shr bx,cl add bx,17 mov ah,4AH int 21H mov ax,bx shl ax,cl dec ax mov sp,ax mov bp,sp endm ; Function Request 4B00H EXEC macro path,command,parms mov dx,offset path mov bx,offset parms mov word ptr parms[02h],offset command mov word ptr parms[04h],cs mov word ptr parms[06h],5ch mov word ptr parms[08h],es mov word ptr parms[0ah],6ch mov word ptr parms[0ch],es mov al,0 mov ah,4BH int 21H endm ; Function Request 4B03H EXEC_OVL macro path,parms,seg_addr mov dx,offset path mov bx,offset parms mov parms,seg_addr mov parms[02H],seg_addr mov al,3 mov ah,4BH int 21H endm ; Function Request 4CH END_PROCESS macro return_code mov al,return_code mov ah,4CH int 21H endm ; Function Request 4DH RET_CODE macro mov ah,4DH int 21H endm ; Function Request 4EH FIND_FIRST_FILE macro path,attrib mov dx,offset path mov cx,attrib mov ah,4EH int 21H endm ; Function Request 4FH FIND_NEXT_FILE macro mov ah,4FH int 21H endm ; Function Request 54H GET_VERIFY macro mov ah,54H int 21H endm ; Function Request 56H RENAME_FILE macro old_path,new_path mov dx,offset old_path push ds pop es mov di,offset new_path mov ah,56H int 21H endm ; Function Request 57H GET_SET_DATE_TIME macro handle,action,time,date mov bx,handle mov al,action mov cx,word ptr time mov dx,word ptr date mov ah,57H int 21H endm ; Function Request 58H ALLOC_STRAT macro code,strategy mov bx,strategy mov al,code mov ah,58H int 21H endm ; Function Request 59H GET_ERROR macro mov ah,59 int 21H endm ; Function Request 5AH CREATE_TEMP macro pathname,attrib mov cx,attrib mov dx,offset pathname mov ah,5AH int 21H endm ; Function Request 5BH CREATE_NEW macro pathname,attrib mov cx,attrib mov dx,offset pathname mov ah,5BH int 21H endm ; Function Request 5C00H LOCK macro handle,start,bytes mov bx,handle mov cx,word ptr start mov dx,word ptr start+2 mov si,word ptr bytes mov di,word ptr bytes+2 mov al,0 mov ah,5CH int 21H endm ; Function Request 5C01H UNLOCK macro handle,start,bytes mov bx,handle mov cx,word ptr start mov dx,word ptr start+2 mov si,word ptr bytes mov di,word ptr bytes+2 mov al,1 mov ah,5CH int 21H endm ; Function Request 5E00H GET_MACHINE_NAME macro buffer mov dx,offset buffer mov al,0 mov ah,5EH int 21H endm ; Function Request 5E02H PRINTER_SETUP macro index,lgth,string mov bx,index mov cx,lgth mov dx,offset string mov al,2 mov ah,5EH int 21H endm ; Function Request 5F02H GET_LIST macro index,local,remote mov bx,index mov si,offset local mov di,offset remote mov al,2 mov ah,5FH int 21H endm ; Function Request 5F03H REDIR macro device,value,source,destination mov bl,device mov cx,value mov si,offset source mov es,seg destination mov di,offset destination mov al,03H mov ah,5FH int 21H endm ; Function Request 5F04H CANCEL_REDIR macro local mov si,offset local mov al,4 mov ah,5FH int 21H endm ; Function Request 62H GET_PSP macro mov ah,62H int 21H endm ; ; ; ******************* ; General ; ******************* ; DISPLAY_ASCIZ macro asciz_string local search,found_it mov bx,offset asciz_string search: cmp byte ptr [bx],0 je found_it inc bx jmp short search found_it: mov byte ptr [bx],"$" display asciz_string mov byte ptr [bx],0 display_char 0DH display_char 0AH endm ; MOVE_STRING macro source,destination,count push es push ds pop es assume es:code mov si,offset source mov di,offset destination mov cx,count rep movs es:destination,source assume es:nothing pop es endm ; CONVERT macro value,base,destination local table,start jmp start table db "0123456789ABCDEF" start: push ax push bx push dx mov al,value xor ah,ah xor bx,bx div base mov bl,al mov al,cs:table[bx] mov destination,al mov bl,ah mov al,cs:table[bx] mov destination[1],al pop dx pop bx pop ax endm ; CONVERT_TO_BINARY macro string,number,value local ten,start,calc,mult,no_mult jmp start ten db 10 start: mov value,0 xor cx,cx mov cl,number xor si,si calc: xor ax,ax mov al,string[si] sub al,48 cmp cx,2 jl no_mult push cx dec cx mult: mul cs:ten loop mult pop cx no_mult: add value,ax inc si loop calc endm ; CONVERT_DATE macro dir_entry mov dx,word ptr dir_entry[24] mov cl,5 shr dl,cl mov dh,dir_entry[24] and dh,1FH xor cx,cx mov cl,dir_entry[25] shr cl,1 add cx,1980 endm ; PACK_DATE macro date local set_bit ; ; On entry: DH=day, DL=month, CX=(year-1980) ; sub cx,1980 push cx mov date,dh mov cl,5 shl dl,cl pop cx jnc set_bit or cl,80h set_bit: or date,dl rol cl,1 mov date[1],cl endm ; ──────────────────────────────────────────────────────────────────────────── Chapter 2 MS-DOS Device Drivers 2.1 Introduction 2.2 Format of a Device Driver 2.3 How to Create a Device Driver 2.3.1 Device Strategy Routine 2.3.2 Device Interrupt Routine 2.4 Installing Device Drivers 2.5 Device Headers 2.5.1 Pointer to Next Device Field 2.5.2 Attribute Field 2.5.3 Strategy and Interrupt Routines 2.5.4 Name Field 2.6 Request Header 2.6.1 Length of Record 2.6.2 Unit Code Field 2.6.3 Command Code Field 2.6.4 Status Field 2.7 Device Driver Functions 2.7.1 The Init Function 2.7.2 The Media Check Function 2.7.3 The Build BPB Function 2.7.4 The Read or Write Function 2.7.5 The Non-destructive Read, No Wait Function 2.7.6 The Open or Close Function 2.7.7 The Removable Media Function 2.7.8 The Status Function 2.7.9 The Flush Function 2.7.10 The Generic IOCtl Function 2.7.11 The Get/Set Logical Drive Map Function 2.8 The Media Descriptor Byte 2.9 Format of a Media Descriptor Table 2.10 The CLOCK Device 2.11 Anatomy of a Device Call 2.12 Two Sample Device Drivers 2.1 Introduction The io.sys file comprises the "resident" device drivers, which form the MS-DOS BIOS. These drivers are called upon by MS-DOS to handle input/output (I/O) requests initiated by application programs. One of the most powerful features of MS-DOS is the ability to add new devices such as printers, plotters, and mouse input devices without rewriting the BIOS. The MS-DOS BIOS is configurable; that is, new drivers can be added and existing drivers can be preempted. Nonresident, or installable, device drivers may be easily added at boot time by including a device command line in the config.sys file. At boot time, a minimum of five resident device drivers must be present. These drivers are in a linked list: the header of each one contains a DWORD pointer to the next. The last driver in the chain has an end-of-list marker of -1, -1 (all bits on). Each driver in the chain has two entry points: the strategy entry point and the interrupt entry point. MS-DOS does not take advantage of the two entry points: it calls the strategy routine, then immediately calls the interrupt routine. The dual entry points will accomodate future multitasking versions of MS-DOS. In multitasking environments, I/O must be asynchronous; to accomplish this, the strategy routine will be called to (internally) queue a request and return quickly. It is then the responsibility of the interrupt routine to perform the I/O at interrupt time by getting requests from the internal queue and processing them. When a request is completed, it is flagged as "done" by the interrupt routine. MS-DOS periodically scans the list of requests looking for those that are flagged as done, and "wakes up" the process waiting for the completion of the request. When requests are queued in this manner, it is no longer sufficient to pass I/O information in registers, since many requests may be pending at any time. Therefore, the MS-DOS device interface uses "packets" to pass request information. These request packets vary in size and format, and are composed of two parts: 1. The static request header section, which has the same format for all requests 2. A section which has information specific to the type of request A driver is called with a pointer to a packet. In multitasking versions, this packet will be linked into a global chain of all pending I/O requests maintained by MS-DOS. MS-DOS does not implement a global or local queue. Only one request is pending at any one time. The strategy routine must store the address of the packet at a fixed location, and the interrupt routine, which is called immediately after the strategy routine, should process the packet by completing the request and returning. It is assumed that the request is completed when the interrupt routine returns. To make a device driver that sysinit can install, a .bin (core image) or .exe format file must be created with the device driver header at the beginning of the file. The link field should be initialized to -1 (sysinit fills it in). Device drivers which are part of the BIOS should have their headers point to the next device in the list and the last header should be initialized to -1,-1. The BIOS must be a .bin (core image) format file. The .exe format installable device drivers may be used in non-IBM versions of MS-DOS. On the IBM Personal Computer, the .exe loader is located in command.com, which is not present at the time that installable devices are being loaded. 2.2 Format of a Device Driver A device driver is a program segment responsible for communication between DOS and the system hardware. It has a special header at the beginning identifying it as a device driver, defining entry points, and describing various attributes of the device. ────────────────────────────────────────────────────────────────────────── Note For device drivers, the file must not use the ORG 100H (like .com files). Because it does not use the Program Segment Prefix (PSP), the device driver is simply loaded; therefore, the file must have an origin of zero (ORG 0 or no ORG statement). ────────────────────────────────────────────────────────────────────────── There are two kinds of device drivers: ■ Character device drivers ■ Block device drivers Character devices perform serial character I/O. Examples are the console, communications port, and printer. These devices are named (i.e., CON, AUX, CLOCK, etc.), and programs may open channels (handles or file control blocks) to do I/O to them. Block devices include all the disk drives on the system. They can perform random I/O in structured pieces called blocks (usually the physical sector size). These devices are not named as the character devices are and, therefore, cannot be opened directly. Instead they have unit numbers and are identified by drive letters such as A, B, and C. A single block device driver may be responsible for one or more logically contiguous disk drives. For example, block device driver ALPHA may be responsible for drives A, B, C, and D. This means that it has four units defined (0-3) and, therefore, takes up four drive letters. The position of the driver in the list of all drivers determines which units correspond to which driver letters. If driver ALPHA is the first block driver in the device list, and it defines four units (0-3), then they will be A, B, C, and D. If BETA is the second block driver and defines three units (0-2), then they will be E, F, and G, and so on. The theoretical limit is 63, but it should be noted that the device installation code will not allow the installation of a device if it would result in a drive letter greater than Z (5AH). All block device drivers present in the standard resident BIOS will be placed ahead of installable block device drivers in the list. ────────────────────────────────────────────────────────────────────────── Note Because they have only one name, character devices cannot define multiple units. ────────────────────────────────────────────────────────────────────────── 2.3 How to Create a Device Driver To create a device driver that MS-DOS can install, you must create a binary file (.com or .exe format) with a device header at the beginning of the file. Notice that for device drivers, the code should not be originated at 100H, but at 0. The device header contains a link field (a pointer to the next device header) that should be -1, unless there is more than one device driver in the file. The attribute field and entry points must be set correctly. If it is a character device, the name field should be filled in with the name of that character device. The name can be any legal eight-character filename. If the name is less than eight characters, it should be padded out to eight characters with spaces (20H). Notice that device names do not include colons (:). The fact that CON is the same as CON: is a property of the default MS-DOS command interpreter (command.com) and not of the device driver or the MS-DOS interface. All character device names are handled in this way. MS-DOS always processes installable device drivers before handling the default devices; so, to install a new CON device, simply name the device CON. Remember to set the standard input device and standard output device bits in the attribute word on a new CON device. The scan of the device list stops on the first match, so the installable device driver takes precedence. It is not possible to replace the resident disk block device driver with an installable device driver the same way you can replace the other device drivers in the BIOS. Block drivers can be used only for devices not directly supported by the default disk drivers in AE@% database installed. As an example, if your SQL Server is named sql_svr, e Note Because MS-DOS can install the driver anywhere in memory, care must be taken when making far memory references. You should not expect that your driver will always be loaded in the same place every time. ────────────────────────────────────────────────────────────────────────── 2.3.1 Device Strategy Routine The device strategy routine, which is called by MS-DOS for each device driver service request, is primarily responsible for queuing these requests in the order in which they are to be processed by the device interrupt routine. Such queuing can be a very important performance feature in a multitasking environment, or where asynchronous I/O is supported. As MS-DOS does not currently support these facilities, only one request can be serviced at a time, and this routine is usually very short. In the coding examples in Section 2.12, "Two Sample Device Drivers," each request is simply stored in a single pointer area. 2.3.2 Device Interrupt Routine The device interrupt routine contains the code necessary to process the service request. It may interface to the hardware, or it may use ROM BIOS calls. It usually consists of a series of procedures that handle the specific command codes to be supported as well as some exit and error-handling routines. See the coding examples in Section 2.12, "Two Sample Device Drivers." 2.4 Installing Device Drivers MS-DOS allows new device drivers to be installed dynamically at boot time. This is accomplished by initialization code in the io.sys file that reads and processes the config.sys file. MS-DOS calls upon the device drivers to perform their function in the following manner: 1. MS-DOS makes a FAR call to the strategy entry. 2. MS-DOS passes device driver information in a request header to the strategy routine. 3. MS-DOS makes a FAR call to the interrupt entry. This calling structure is designed to be easily upgraded to support any future multitasking environment. 2.5 Device Headers A device header is required at the beginning of a device driver. A device header looks like this: ┌──────────────────────────────────────┐ │ DWORD Pointer to next device │ │ (Usually set to -1 if this driver │ │ is the last or only driver in the │ │ file) │ ├──────────────────────────────────────┤ │ WORD Attributes │ ├──────────────────────────────────────┤ │ WORD Pointer to device strategy │ │ entry point │ ├──────────────────────────────────────┤ │ WORD Pointer to device interrupt │ │ entry point │ ├──────────────────────────────────────┤ │ 8-BYTE Character device name field │ │ Character devices set a device name. │ │ For block devices the first byte is │ │ the number of units. │ └──────────────────────────────────────┘ Figure 2.1 Sample Device Header Notice that the device entry points are words. They must be offsets from the same segment number used to point to this table. For example, if xxx:yyy points to the start of this table, then xxx:strategy and xxx:interrupt are the entry points. The device header fields are described in the following section. 2.5.1 Pointer to Next Device Field The pointer to the next device header field is a double-word field (offset followed by segment) that is set by MS-DOS to point at the next driver in the system list at the time the device driver is loaded. It is important that this field be set to -1 prior to load (when it is on the disk as a file) unless there is more than one device driver in the file. If there is more than one driver in the file, the first word of the double-word pointer should be the offset of the next driver's device header. ────────────────────────────────────────────────────────────────────────── Note If there is more than one device driver in the file, the last driver in the file must have the pointer to the next device header field set to -1. ────────────────────────────────────────────────────────────────────────── 2.5.2 Attribute Field The attribute field is used to identify the type of device for which this driver is responsible. In addition to distinguishing between block and character devices, these bits are used to give selected character devices special treatment. (Notice that if a bit in the attribute word is defined only for one type of device, a driver for the other type of device must set that bit to 0.) Table 2.1 For Character Devices: Bit Value Meaning ────────────────────────────────────────────────────────────────────────── 0 1 Device is console input (sti) device 1 1 Device is console output (sto) device 2 1 Device is nul device 3 1 Device is clock device 4-5 Reserved (must be 0) 6 1 Device supports 3.2 functions 7-10 Reserved (must be 0) 11 1 Device understands Open/Close 12 Reserved (must be 0) 13 1 Device supports Output Until Busy (OUB) 14 1 Device supports IOCtl control strings 15 1 Character device ────────────────────────────────────────────────────────────────────────── Table 2.2 For Block Devices: Bit Value Meaning ────────────────────────────────────────────────────────────────────────── 0 Reserved (must be 0) 1 1 Device supports 32-bit sector addressing 2-5 Reserved (must be 0) 6 1 Device supports 3.2 functions and Generic IOCtl function calls 7-10 Reserved (must be 0) 11 1 Device understands Open/Close/Removable Media 12 Reserved (must be 0) 13 1 Device determines the media by examining the FATID byte 14 1 Device supports IOCtl control strings 15 0 Block device ────────────────────────────────────────────────────────────────────────── For example, assume that you have a new device driver that you want to use as the standard input and output. In addition to installing the driver, you must tell MS-DOS that you want the new driver to override the current standard input and standard output (the CON device). This is accomplished by setting the attributes to the desired characteristics, so you would set bits 0 and 1 to 1 (notice that they are separate). Similarly, a new CLOCK device could be installed by setting that attribute. (Refer to Section 2.10, "The CLOCK Device," in this chapter for more information.) Although there is a NUL device attribute, the NUL device cannot be reassigned. This attribute exists so that MS-DOS can determine if the NUL device is being used. Bit 13 for block devices affects the operation of the Build BPB (BIOS Parameter Block) device call. If set, it requires the first sector of the FAT always to reside in the same place. This bit has a different meaning on character devices. It indicates that the device implements the Output Until Busy device call. The IOCtl bit (bit 14) has meaning on character and block devices. The IOCtl functions allow data to be sent and received by the device for its own use (to set baud rate, stop bits, form length, etc.) instead of passing data over the device channel as a normal read or write does. The interpretation of the passed information is up to the device but it must not be treated as normal I/O. This bit tells MS-DOS whether the device can handle control strings by using the IOCtl system call, Function 44H. If a driver cannot process control strings, it should initially set this bit to 0. This tells MS-DOS to return an error if an attempt is made (via Function 44H) to send or receive control strings to this device. A device which can process control strings should initialize the IOCtl bit to 1. For drivers of this type, MS-DOS will make calls to the IOCtl input and output device functions to send and receive IOCtl strings. The IOCtl functions allow data to be sent and received by the device for its own use (for example, to set baud rate, stop bits, and form length), instead of passing data over the device channel as does a normal read or write. The interpretation of the passed information is up to the device, but it must not be treated as a normal I/O request. The Open/Close/Removable Media bit (bit 11) signals to MS-DOS 3.x and later versions whether this driver supports additional MS-DOS 3.x functionality. To support these old drivers, it is necessary to detect them. This bit was reserved in MS-DOS 2.x, and is 0. All new devices should support the Open, Close, and Removable Media calls and set this bit to 1. Since MS-DOS 2.x never makes these calls, the driver will be backward-compatible. The MS-DOS 3.2 bit (bit 6) signals whether the device supports logical drive mapping via Function 440EH (Get Logical Drive Map) and Function 440FH (Set Logical Drive Map). This bit also supports generic IOCtl functions via Function 440CH (Generic IOCtl for Handles) and Function 440DH (Generic IOCtl for Block Devices). Bit 1 for block devices indicates the driver's ability to manipulate 32-bit sector addresses. If bit 1 = 1, 32-bit sector addressing is supported. If bit 1 is set, the sector number field of all requests is a DWORD added to the end of the request header. The old WORD length sector number should be -1. The driver requests affected are: ■ BUILD BPD command 2 ■ INPUT/OUTPUT command 3 ,4, 8, 9, and 12 ■ GENERIC IOCTL command 19 If bit 1 for block devices is 0, only 16-bit sector addressing is available. 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ │ C │ I │ │ │ O │ │ │ │ │ 3 │ │ │ C │ N │ S │ S │ │ H │ O │ │ │ P │ │ │ │ │ . │ │ │ L │ U │ T │ T │ │ R │ C │ │ │ N │ │ │ │ │ 2 │ │ │ K │ L │ O │ I │ └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘ Figure 2.2 Attribute Word for Character Devices 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 ┌───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┬───┐ │ │ I │ F │ │ O │ │ │ │ │ 3 │ │ │ │ │ > │ │ │ │ O │ A │ │ P │ │ │ │ │ . │ │ │ │ │ 3 │ │ │ │ C │ T │ │ N │ │ │ │ │ 2 │ │ │ │ │ 2 │ │ └───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┴───┘ Figure 2.3 Attribute Word for Block Devices 2.5.3 Strategy and Interrupt Routines These two fields are the pointers to the entry points of the strategy and interrupt routines. They are word values, so they must be in the same segment as the device header. 2.5.4 Name Field This is an eight-byte field that contains the name of a character device or the number of units of a block device. If the field refers to a block device, the number of units can be put in the first byte. This is optional, because MS-DOS will fill in this location with the value returned by the driver's Init code. For more information, see Section 2.4, "Installing Device Drivers." 2.6 Request Header When MS-DOS calls a device driver to perform a function, it passes a request header in ES:BX to the strategy entry point. This is a fixed length header, followed by data pertinent to the operation being performed. Notice that it is the device driver's responsibility to preserve the machine state (for example, save all registers, including flags, on entry, and restore them on exit). There is enough room on the stack when the strategy or interrupt routine is called to do about 20 pushes. If more room on the stack is needed, the driver should set up its own stack. The following figure illustrates a request header. REQUEST HEADER -> ┌─────────────────────────────┐ │ BYTE Length of record │ │ Length in bytes of this │ │ request header │ ├─────────────────────────────┤ │ BYTE Unit code │ │ The subunit the operation │ │ is for (minor device) │ │ (no meaning on character │ │ devices) │ ├─────────────────────────────┤ │ BYTE Command code │ ├─────────────────────────────┤ │ WORD Status │ ├─────────────────────────────┤ │ 8 BYTES Reserved │ │ │ └─────────────────────────────┘ Figure 2.4 Request Header The request header fields are described below. 2.6.1 Length of Record This field contains the length (in bytes) of the request header. 2.6.2 Unit Code Field The unit code field identifies which unit in your device driver the request is for. For example, if your device driver has three units defined, then the possible values of the unit code field would be 0, 1, and 2. 2.6.3 Command Code Field The command code field in the request header can have the following values: ╓┌─┌──────────────────┌──────────────────────────────────────────────────────╖ Code Function ────────────────────────────────────────────────────────────────────────── 0 Init 1 Media Check (Block devices only) 2 Build BPB (Block devices only) 3 IOCtl Input (Only called if device has IOCtl) 4 Input (Read) 5 Non-destructive Read, No Wait (Character devices only) 6 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) Code Function ────────────────────────────────────────────────────────────────────────── 11 Output Flush (Character devices only) 12 IOCtl Output (Only called if device has IOCtl) 13 Device Open (Only called if Open/Close/Removable Media bit set) 14 Device Close (Only called if Open/Close/Removable Media bit set) 15 Removable Media (Only called if Open/Close/Removable Media bit set and device is block) 16 Output Until Busy (Only called if bit 13 is set on character devices) 19 Generic IOCtl Request 23 Get Logical Device 24 Set Logical Device ────────────────────────────────────────────────────────────────────────── 2.6.4 Status Field The following figure illustrates the status field in the request header. 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 ┌───┬───────────────┬───┬───┬───────────────────────┐ │ E │ │ B │ D │ │ │ R │ Reserved │ U │ O │ Error code (bit 15 on)│ │ R │ │ S │ N │ │ │ │ │ Y │ E │ │ └───┴───────────────┴───┴───┴───────────────────────┘ Figure 2.5 Status Field The status word is zero on entry and is set by the driver interrupt routine on return. Bit 8 is the done bit. When set, it means the operation has completed. The driver sets it to 1 when it exits. Bit 15 is the error bit. If it is set, then the low eight bits indicate the error. The errors are as follows: Error Meaning ────────────────────────────────────────────────────────────────────────── 0 Write protect violation 1 Unknown unit 2 Drive not ready 3 Unknown command 4 CRC error 5 Bad drive request structure length 6 Seek error 7 Unknown media 8 Sector not found 9 Printer out of paper ────────────────────────────────────────────────────────────────────────── Error Meaning ────────────────────────────────────────────────────────────────────────── A Write fault B Read fault C General failure D Reserved E Reserved F Invalid disk change ────────────────────────────────────────────────────────────────────────── Bit 9 is the busy bit, which is set only by Status calls and the Removable Media call. 2.7 Device Driver Functions Device drivers may perform all or some of these general functions. In some cases, these functions break down into several command codes, for specific cases. Each of the following general functions is described in this section. ■ Init ■ Media Check ■ Build BPB ■ Read, or Write, or Write Until Busy, or Write with Verify, or Read IOCtl, or Write IOCtl ■ Non-destructive Read, No Wait ■ Open or Close (3.x) ■ Removable Media (3.x) ■ Status ■ Flush ■ Generic IOCtl ■ Get or Set Logical Device All strategy routines are called with ES:BX pointing to the request header. The interrupt routines get the pointers to the request header from the queue that the strategy routines store them in. The command code in the request header tells the driver which function to perform and what data follows the request header. ────────────────────────────────────────────────────────────────────────── Note All DWORD pointers are stored offset first, then segment. ────────────────────────────────────────────────────────────────────────── 2.7.1 The Init Function Command code = 0 INIT - ES:BX -> ┌────────────────────────────────────┐ │ 13-BYTE Request header │ ├────────────────────────────────────┤ │ BYTE Number of units │ ├────────────────────────────────────┤ │ DWORD End Address │ ├────────────────────────────────────┤ │ DWORD Pointer to BPB array │ │ (Not set by character devices) │ ├────────────────────────────────────┤ │ BYTE Block device number │ └────────────────────────────────────┘ One of the functions defined for each device driver is Init. This routine is called only once when the device is installed. The Init routine must return the end address, which is a DWORD pointer to the end of the portion of the device driver to remain resident. To save space, you can use this pointer method to delete initialization code that is needed only once. The number of units, end address, and BPB pointer are to be set by the driver. However, on entry for installable device drivers, the DWORD that is to be set by the driver to the BPB array (on block devices) points to the character after the "=" on the line in config.sys that caused this device driver to be loaded. This allows drivers to scan the config.sys invocation line for parameters that might be passed to the driver. This line is terminated by an ENTER or a linefeed character. This data is read-only and allows the device to scan the config.sys command line for arguments. device=\dev\vt52.sys /l │ └─────BPB address points here Also, for block devices only, the drive number assigned to the first unit defined by this driver (A=0) is contained in the block device number field. This is also read-only. ────────────────────────────────────────────────────────────────────────── Note The Init routine can issue only Functions 01H-0CH, 25H, 30H, and 35H. ────────────────────────────────────────────────────────────────────────── For installable character devices, the end address parameter must be returned. This is a pointer to the first available byte of memory above the driver and may be used to throw away initialization code. Block devices must return the following information: 1. The number of units. MS-DOS uses this number to determine logical device names. If the current maximum logical device letter is F at the time of the install call, and the Init routine returns 4 as the number of units, then they will have logical names G, H, I, and J. This mapping is determined by the position of the driver in the device list, and by the number of units on the device (stored in the first byte of the device name field). 2. A DWORD pointer to an array of word offsets (pointers) to BPBs (BIOS Parameter Blocks). The BPBs passed by the device driver are used by MS-DOS to create an internal structure. There must be one entry in this array for each unit defined by the device driver. In this way, if all units are the same, all the pointers can point to the same BPB, thereby saving space. If the device driver defines two units, then the DWORD pointer points to the first of two one-word offsets which in turn point to BPBs. The format of the BPB is described in Section 2.7.3, "The Build BPB Function." Notice that this array of word offsets must be protected (below the free pointer set by the return), since an internal DOS structure will be built starting at the byte pointed to by the free pointer. The defined sector size must be less than or equal to the maximum sector size defined by the resident device drivers (BIOS) during initialization. If it isn't, the installation will fail. 3. The media descriptor byte. This byte means nothing to MS-DOS, but is passed to devices so that they know what parameters MS-DOS is currently using for a particular drive. ────────────────────────────────────────────────────────────────────────── Note If there are multiple device drivers in a single file, MS-DOS uses the ending address returned by the last Init function called. All device drivers in a single file should return the same ending address. All devices in a single file should be grouped together low in memory with the initialization code for all devices following it in memory. ────────────────────────────────────────────────────────────────────────── 2.7.2 The Media Check Function Command Code = 1 MEDIA CHECK - ES:BX -> ┌────────────────────────────────────┐ │ 13-BYTE Request header │ ├────────────────────────────────────┤ │ BYTE Media descriptor from BPB │ ├────────────────────────────────────┤ │ BYTE Returned │ │────────────────────────────────────┤ │ Returned DWORD pointer to previous │ │ Volume ID if bit 11 set and │ │ Disk Changed is returned │ └────────────────────────────────────┘ The Media Check function is used only with block devices. It is called when there is a pending drive-access call other than a file read or write, such as Open, Close, delete, and rename. Its purpose is to determine whether the media in the drive has been changed. If the driver can assure that the media has not been changed (through a door-lock or other interlock mechanism), MS-DOS performance is enhanced, because MS-DOS does not need to reread the FAT and invalidate in-memory buffers for each directory access. When a disk-access call to the DOS occurs (other than a file read or write), the following sequence of events takes place: 1. The DOS converts the drive letter into a unit number of a particular block device. 2. The device driver is then called to request a media check on that subunit to see if the disk might have been changed. MS-DOS passes the old media descriptor byte. The driver returns one of the following: Return Meaning ─────────────────────────────────────────────────────────────────────── (1) Media not changed (0) Don't know if changed (-1) Media changed value Error (value is a standard error code value) ─────────────────────────────────────────────────────────────────────── If the media has not been changed, MS-DOS proceeds with the disk access. If the value returned is -1, and there are any disk sectors that have been modified and not written back out to the disk for this unit, MS-DOS assumes that the disk has not been changed and proceeds. MS-DOS invalidates any other buffers for the unit and does a Build BPB call (see Step 3, following). If the media has been changed, MS-DOS invalidates all buffers associated with this unit including buffers with modified data that are waiting to be written, and requests a new BIOS Parameter Block via the Build BPB call (see Step 3). 3. Once the BPB has been returned, MS-DOS corrects its internal structure for the drive from the new BPB and proceeds with the access after reading the directory and the FAT. Notice that the previous media ID byte is passed to the device driver. If the old media ID byte is the same as the new one, the disk might have been changed and a new disk may be in the drive; therefore, all FAT, directory, and data sectors that are buffered in memory for the drive are considered invalid. If the driver has bit 11 of the device attribute word set to 1, and the driver returns -1 (Media Changed), the driver must set the DWORD pointer to the previous Volume ID field. If the DOS determines that "Media changed" is an error based on the state of the DOS buffer cache, the DOS will generate a 0FH error on behalf of the device. If the driver does not implement volume ID support, but has bit 11 set, it should set a static pointer to the string "NO NAME" ,0. It is not possible for a user to change a disk in less than two seconds. So when Media Check occurs within two seconds of a disk access, the driver reports "Media not changed (1)." This improves performance tremendously. ────────────────────────────────────────────────────────────────────────── Note If the media ID byte in the returned BPB is the same as the previous media ID byte, MS-DOS will assume that the format of the disk is the same (even though the disk may have been changed) and will skip the step of updating its internal structure. Therefore, all BPBs must have unique media bytes regardless of FAT ID bytes. ────────────────────────────────────────────────────────────────────────── 2.7.3 The Build BPB Function Command code = 2 BUILD BPB - ES:BX -> ┌────────────────────────────────────┐ │ 13-BYTE Request header │ ├────────────────────────────────────┤ │ BYTE Media descriptor from BPB │ ├────────────────────────────────────┤ │ DWORD Transfer address │ │ (Points to one sector worth of │ │ scratch space or first sector │ │ of FAT depending on the value │ │ of Bit 13 in the device attribute │ │ word.) │ ├────────────────────────────────────┤ │ DWORD Pointer to BPB │ └────────────────────────────────────┘ The Build BPB function is used with block devices only. As described in the Media Check function, the Build BPB function will be called any time that a preceding Media Check call indicates that the disk has been or might have been changed. The device driver must return a pointer to a BPB. This is different from the Init call where the device driver returns a pointer to an array of word offsets to BPBs. The Build BPB call gets a DWORD pointer to a one-sector buffer. The contents of this buffer are determined by the non-FAT ID bit (bit 13) in the attribute field. If the bit is zero, then the buffer contains the first sector of the first FAT. The FAT ID byte is the first byte of this buffer. In this case, the driver must not alter this buffer. Notice that the location of the FAT must be the same for all possible media because this first FAT sector must be read before the actual BPB is returned. If the non-FAT ID bit is set, the pointer points to one sector of scratch space (which may be used for anything). For information on how to construct the BPB, see Section 2.8, "The Media Descriptor Byte," and Section 2.9, "Format of a Media Descriptor Table." MS-DOS 4.0 includes additional support for devices that have door-locks or some other means of telling when a disk has been changed. There is an error that can be returned from the device driver (error 15). The error means "the disk has been changed when it shouldn't have been," and the user is prompted for the correct disk using a volume ID. The driver may generate this error on read or write. The DOS may generate the error on Media Check calls if the driver reports media changed and there are buffers in the DOS buffer cache that need to be flushed to the previous disk. For drivers that support this error, the Build BPB function is a trigger that causes a new volume ID to be read off the disk. This action indicates that the disk has been legally changed. A volume ID is placed on a disk by the format command and is simply an entry in the root directory of the disk that has the Volume ID attribute. It is stored by the driver as an ASCIZ string. The requirement that the driver return a volume ID does not exclude some other volume identifier scheme as long as the scheme uses ASCIZ strings. A NUL (nonexistent or unsupported) volume ID is by convention the following string: DB "NO NAME ",0 2.7.4 The Read or Write Function Command codes = 3,4,8,9,12, and 16 READ OR WRITE (Including IOCtl) or OUTPUT UNTIL BUSY - ES:BX -> ┌────────────────────────────────────┐ │ 13-BYTE Request header │ ├────────────────────────────────────┤ │ BYTE Media descriptor from BPB │ ├────────────────────────────────────┤ │ DWORD Transfer address │ ├────────────────────────────────────┤ │ WORD Byte/sector count │ ├────────────────────────────────────┤ │ WORD Starting sector number │ │ or -1 if the drive supports │ │ greater than 16-bit sector │ │ addresses │ │ (Ignored on character devices) │ ├────────────────────────────────────┤ │ DWORD pointer to the Volume ID │ ├────────────────────────────────────┤ │ Starting sector number │ │ (high-word first) if WORD starting │ │ sector number is -1 │ │ or │ │ Returned DWORD pointer to requested│ │ Volume ID if error 0FH │ └────────────────────────────────────┘ Code Request ────────────────────────────────────────────────────────────────────────── 3 IOCtl read 4 Read (block or character device) 8 Write (block or character device) 9 Write with Verify 12 IOCtl Write 16 Output Until Busy (character device only) ────────────────────────────────────────────────────────────────────────── The driver must perform the Read or Write call depending on which command code is set. Block devices read or write sectors; character devices read or write bytes. When I/O completes, the device driver must set the status word and report the number of sectors or bytes successfully transferred. This should be done even if an error prevented the transfer from being completed. Setting the error bit and error code alone is not sufficient. In addition to setting the status word, the driver must set the sector count to the actual number of sectors (or bytes) transferred. No error check is performed on an IOCtl I/O call. The device driver must always set the return byte/sector count to the actual number of bytes/sectors successfully transferred. If the verify switch is on, the device driver will be called with command code 9 (Write with Verify). Your device driver will be responsible for verifying the write. If the driver returns error code 0FH (Invalid disk change), it must return a DWORD pointer to an ASCIZ string (which is the correct volume ID). Returning this error code triggers the DOS to prompt the user to re-insert the disk. The device driver should have read the volume ID as a result of the Build BPB function. Drivers may maintain a reference count of open files on the disk by monitoring the Open and Close functions. This allows the driver to determine when to return error 0FH. If there are no open files (reference count = 0), and the disk has been changed, the I/O is okay. If there are open files, however, an 0FH error may exist. The Output Until Busy call is a speed optimization on character devices only for print spoolers. The device driver is expected to output all the characters possible until the device returns busy. Under no circumstances should the device driver block during this function. Notice that it is not an error for the device driver to return the number of bytes output as being less than the number of bytes requested (or = 0). The Output Until Busy call allows spooler programs to take advantage of the "burst" behavior of most printers. Many printers have on-board RAM buffers that typically hold a line or a fixed amount of characters. These buffers fill up without the printer going busy, or going busy for a short period (less than ten instructions) between characters. A line of characters can be output quickly to the printer, after which the printer is busy for a long time while the characters are being printed. This new device call allows background spooling programs to use this burst behavior efficiently. Rather than take the overhead of a device driver call for each character, or risk getting stuck in the device driver outputting a block of characters, this call allows a burst of characters to be output without the device driver having to wait for the device to be ready. The Following Applies to Block Device Drivers: Under certain circumstances, the BIOS may be asked to perform a write operation of 64 kilobytes, which seems to be a "wrap-around" of the transfer address in the BIOS I/O packet. This request, which arises due to an optimization added to the write code in MS-DOS, will manifest itself only on user writes that are within a sector size of 64 kilobytes on files "growing" past the current end-of-file (EOF) mark. It is allowable for the BIOS to ignore the balance of the write that "wraps around" if it so chooses. For example, a write of 10000H bytes-worth of sectors with a transfer address of xxx:1 could ignore the last two bytes. A user program can never request an I/O of more than FFFFH bytes and cannot wrap around (even to 0) in the transfer segment. Therefore, in this case, the last two bytes can be ignored. MS-DOS maintains two FATs. If the DOS has problems reading the first, it automatically tries the second before reporting the error. The BIOS is responsible for all retries. Although the command.com handler does no automatic retries, there are applications that have their own Interrupt 24H handlers that do automatic retries on certain types of Interrupt 24H errors before reporting them. 2.7.5 The Non-destructive Read, No Wait Function Command code = 5 NON-DESTRUCTIVE READ NO WAIT - ES:BX -> ┌────────────────────────────────────┐ │ 13-BYTE Request header │ ├────────────────────────────────────┤ │ BYTE Read from device │ └────────────────────────────────────┘ The Non-destructive Read, No Wait function allows MS-DOS to look ahead one input character. The device sets the done bit in the status word. If the character device returns busy bit = 0 (there are characters in the buffer), then the next character that would be read is returned. This character is not removed from the input buffer (hence the term "Non-destructive Read"). If the character device returns busy bit = 1, there are no characters in the buffer. 2.7.6 The Open or Close Function Command codes = 13 and 14 OPEN or CLOSE - ES:BX -> ┌────────────────────────────────────┐ │ 13-BYTE Static request header │ └────────────────────────────────────┘ The Open and Close functions are called by MS-DOS only if the device driver sets the Open/Close/Removable Media attribute bit in the device header. They are designed to inform the device about current file activity on the device. On block devices, they can be used to manage local buffering. The device can keep a reference count. Every Open causes the device to increment the count, every Close to decrement. When the count goes to zero, it means there are no open files on the device. Therefore, the device should flush any buffers that have been written to that may have been used inside the device, because it is now "legal" for the user to change the media on a removable media drive. There are problems with this mechanism on block devices because programs that use FCB calls can open files without closing them. It is, therefore, advisable to reset the count to zero without flushing the buffers when the answer to "Has the media been changed?" is yes, and the Build BPB call is made to the device. These calls are more useful on character devices. The Open call, for instance, can be used to send a device initialization string. On a printer, this could cause a string for setting font and page size characteristics to be sent to the printer so that it would always be in a known state at the start of an I/O stream. Using IOCtl to set these pre- and post- strings provides a flexible mechanism of serial I/O device stream control. The reference count mechanism can also be used to detect a simultaneous access error. It may be desirable to disallow more than one Open on a device at any given time. In this case, a second Open would result in an error. Notice that since all processes have access to stdin, stdout, stderr, stdaux, and stdprn (handles 0,1,2,3,4), the CON, AUX, and PRN devices are always open. 2.7.7 The Removable Media Function Command code = 15 REMOVABLE MEDIA - ES:BX -> ┌────────────────────────────────────┐ │ 13-BYTE Static request header │ └────────────────────────────────────┘ The Removable Media function is called by MS-DOS only if the device driver sets the Open/Close/Removable Media attribute bit in the device header. This call is given only to block devices by a subfunction of the IOCtl system call. It is sometimes desirable for a utility to know whether it is dealing with a nonremovable media drive (such as a hard disk), or a removable media drive (like a floppy). An example is the format command, which prints different versions of some of the prompts. The information is returned in the busy bit of the status word. If the busy bit is 1, then the media is nonremovable. If the busy bit is 0, then the media is removable. Notice that the error bit is not checked. It is assumed that this call always succeeds. 2.7.8 The Status Function Command codes = 6 and 10 STATUS Calls ES:BX -> ┌────────────────────────────────────┐ │ 13-BYTE Request header │ └────────────────────────────────────┘ The Status function returns information to the DOS as to whether data is waiting for input or output. All the driver must do is set the status word and the busy bit as follows: ■ For output on character devices ── if the driver sets bit 9 to 1 on return, it informs the DOS that a write request (if made) would wait for completion of a current 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 ── A return of 1 implies that no characters are buffered and that a read request (if made) would go to the physical device. If it is 0 on return, then there are characters in the device buffer and a read would not be blocked. A return of 0 implies that the user has typed something. MS-DOS assumes that all character devices have an input type-ahead buffer. Devices that do not have a type-ahead buffer should always return busy = 0 so that the DOS will not "hang" waiting for something to get into a non-existent buffer. 2.7.9 The Flush Function Command codes = 7 and 11 FLUSH Calls - ES:BX -> ┌────────────────────────────────────┐ │ 13-BYTE Request header │ └────────────────────────────────────┘ The Flush function tells the driver to flush (terminate) all pending requests. This call is used to flush the input queue on character devices. The device driver performs the flush function, sets the status word, and returns. 2.7.10 The Generic IOCtl Function Command code = 19 ES:BX -> ┌────────────────────────────────────┐ │ 13-BYTE Static request header │ ├────────────────────────────────────┤ │ BYTE Category (Major) code │ ├────────────────────────────────────┤ │ BYTE Function (Minor) code │ ├────────────────────────────────────┤ │ WORD (SI) Contents │ ├────────────────────────────────────┤ │ WORD (DI) Contents │ ├────────────────────────────────────┤ │ DWORD Pointer to data buffer │ └────────────────────────────────────┘ The Generic IOCtl function provides a generic, expandable IOCtl facility that replaces and makes the Read IOCtl and Write IOCtl device driver functions obsolete. The MS-DOS 2.0 IOCtl functions remain to support existing uses of the IOCtl system call (Subfunctions 2, 3, 4, and 5), but new device drivers should use this generic MS-DOS IOCtl facility. The Generic IOCtl function contains both a category and function code. The DOS examines the category field in order to intercept and obey device commands that are actually serviced by the DOS code; all other command categories are forwarded to the device driver for servicing. For more information on these category and function codes, refer to Function 440CH (Generic IOCtl for Handles) and Function 440DH (Generic IOCtl for Block Devices) in Chapter 1, "System Calls." 2.7.11 The Get/Set Logical Drive Map Function Command codes = 23 (Get) or 24 (Set) ┌────────────────────────────────────────┐ │ 13-BYTE Static request header │ ├────────────────────────────────────────┤ │ BYTE Input (unit code) │ ├────────────────────────────────────────┤ │ BYTE Output (last device referenced)│ ├────────────────────────────────────────┤ │ BYTE Command code │ ├────────────────────────────────────────┤ │ WORD Status │ ├────────────────────────────────────────┤ │ DWORD Reserved │ └────────────────────────────────────────┘ The Get/Set Logical Drive Map function is called by MS-DOS only if the device driver sets the DOS 3.2 attribute bit in the device header. The call is issued only to block devices by the subfunction of the IOCtl system call. The logical drive to be mapped is passed in the Unit field of the header to the device driver. The device driver returns the current logical drive owner of the physical device that maps to the requested physical drive. To detect whether or not a logical device currently owns the physical device to which it is mapped, a program needs to verify that, after a call of Function 440EH or 440FH (Get/Set Logical Drive Map), the value of the Unit field is unchanged. 2.8 The Media Descriptor Byte In MS-DOS, the media descriptor byte is used to inform the DOS that a different type of media is present. The media descriptor byte can be any value between 0 and FFH. It does not have to be the same as the FAT ID byte. The FAT ID byte, which is the first byte of the FAT, was used in MS-DOS 1.00 to distinguish between different types of disk media, and may be used as well under 2.x and 3.x disk device drivers. However, FAT ID bytes have significance only for block device drivers where the non-FAT ID bit is not set (0). Values of the media descriptor byte or the FAT ID byte have no significance to MS-DOS. They are passed to the device driver so that programs can determine the media type. 2.9 Format of a Media Descriptor Table The MS-DOS file system uses a linked list of pointers (one for each cluster or allocation unit) called the File Allocation Table (FAT). Unused clusters are represented by zero and end-of-file by FFFH (or FFFFH on units with 16-bit FAT entries). No valid entry should ever point to a zero entry, but if one does, the first FAT entry (which would be pointed to by a zero entry) was reserved and set to end of chain. Eventually, several end of chain values were defined ([F]FF8H[F]FFFH), and these were used to distinguish different types of media. A preferable technique is to write a complete media descriptor table in the boot sector and use it for media identification. To ensure backward compatibility for systems whose drivers do not set the non-FAT ID bit (including the IBM PC implementation), it is also necessary to write the FAT ID bytes during the format process. To allow more flexibility for supporting many different disk formats in the future, it is recommended that the information relating to the BPB for a particular piece of media be kept in the boot sector. Figure 2.6 shows the format of such a boot sector. ┌────────────────────────────────────┐ │ 3 BYTE Near JUMP to boot code │ ├────────────────────────────────────┤ │ 8 BYTES OEM name and version │ ├────────────────────────────────────┤ B │ WORD Bytes per sector │ P ├────────────────────────────────────┤ B │ BYTE Sectors per allocation unit │ ├────────────────────────────────────┤ │ WORD Reserved sectors │ ├────────────────────────────────────┤ │ BYTE Number of FATs │ ├────────────────────────────────────┤ │ WORD Number of root dir entries │ ├────────────────────────────────────┤ │ WORD Number of sectors in logical │ │ | image or 0 │ ├────────────────────────────────────┤ B │ BYTE Media descriptor │ P ├────────────────────────────────────┤ B │ WORD Number of FAT sectors │ ├────────────────────────────────────┤ │ WORD Sectors per track │ ├────────────────────────────────────┤ │ WORD Number of heads │ ├────────────────────────────────────┤ │ WORD Number of hidden sectors │ ├────────────────────────────────────┤ │ WORD High order number of hidden │ │ sectors │ ├────────────────────────────────────┤ │ DWORD Number of logical sectors │ └────────────────────────────────────┘ Figure 2.6 Format of a Boot Sector Although MS-DOS does not use the five fields that follow the BPB, these fields may be used by a device driver to help it understand the media. The "Sectors per track" and "Number of heads" fields are useful for supporting different media that may have the same logical layout, but a different physical layout (for example, 40-track, double-sided versus 80-track, single-sided). "Sectors per track" tells the device driver how the logical disk format is laid out on the physical disk. The "Number of hidden sectors" and "High order number of hidden sectors" fields may be used to support drive-partitioning schemes. The "Number of logical sectors" field tells the device driver how many sectors to reserve if the "Number of sectors in logical image" field is zero. (Notice that this is intended for supporting devices that access more than 32 megabytes.) The following procedure is recommended for media determination by NON FAT ID format drivers: 1. Read the boot sector of the drive into the one-sector scratch space pointed to by the DWORD transfer address. 2. Determine if the first byte of the boot sector is an E9H or EBIT (the first byte of a 3-byte NEAR or 2-byte SHORT jump) or an EBH (the first byte of a 2-byte jump followed by an NOP). If so, a BPB is located beginning at offset 3. Return a pointer to it. 3. If the boot sector does not have a BPB table, it is probably a disk formatted under a 1.x version of MS-DOS and probably uses a FAT ID byte for determining media. The driver may optionally attempt to read the first sector of the FAT into the one-sector scratch area and read the first byte to determine media type based upon whatever FAT ID bytes may have been used on disks that are expected to be read by this system. Return a pointer to a hard-coded BPB. 2.10 The CLOCK Device MS-DOS assumes that some sort of clock is available in the system. This may either be a CMOS real-time clock or an interval timer that is initialized at boot time by the user. The CLOCK device defines and performs functions like any other character device, except that it is identified by a bit in the attribute word. The DOS uses this bit to identify it; consequently, the CLOCK device may take any name. The IBM implementation uses the name $CLOCK so as not to conflict with existing files named clock. The CLOCK device is unique in that MS-DOS will read or write a 6-byte sequence that encodes the date and time. A write to this device will set the date and time; a read will get the date and time. Figure 2.7 illustrates the binary time format used by the CLOCK device: byte 0 byte 1 byte 2 byte 3 byte 4 byte 5 ┌────────┬────────┬─────────┬────────┬────────┬─────────┐ │ │ │ │ │ │ │ │days since 1-1-80│ minutes │ hours │ sec/100│ seconds │ │low byte|hi byte │ │ │ │ │ └─────────────────┴─────────┴────────┴────────┴─────────┘ Figure 2.7 Format of a Clock Device 2.11 Anatomy of a Device Call The following steps illustrate what happens when MS-DOS calls on a block device driver to perform a Write request: 1. MS-DOS writes a request packet in a reserved area of memory. 2. MS-DOS calls the strategy entry point of the block device driver. 3. The device driver saves the ES and BX registers (ES:BX points to the request packet) and does a FAR return. 4. MS-DOS calls the interrupt entry point. 5. The device driver retrieves the pointer to the request packet and reads the command code (offset 2) to determine that this is a Write request. The device driver converts the command code to an index into a dispatch table and control passes to the Write routine. 6. The device driver reads the unit code (offset 1) to determine which disk drive it is supposed to write to. 7. Since the command is a disk Write, the device driver must get the transfer address (offset 14), the sector count (offset 18), and the start sector (offset 20) in the request packet. 8. The device driver translates the first logical sector number into a track, head, and sector number. 9. The device driver writes the specified number of sectors, starting at the beginning sector on the drive defined by the unit code (the subunit defined by this device driver), and transfers data from the transfer address indicated in the request packet. Notice that this may involve multiple Write commands to the disk controller. 10.After the transfer is complete, the device driver must report the status of the request to MS-DOS by setting the done bit in the status word (offset 3 in the request packet). It reports the number of sectors actually transferred in the sector count area of the request packet. 11.If an error occurs, the driver sets the done bit and the error bit in the status word and fills in the error code in the lower half of the status word. The number of sectors actually transferred must be written in the request header. It is not sufficient just to set the error bit of the status word. 12.The device driver does a FAR return to MS-DOS. The device drivers should preserve the state of MS-DOS. This means that all registers (including flags) should be preserved. The direction flag and interrupt enable bits are critical. When the interrupt entry point in the device driver is called, MS-DOS has room for about 40 to 50 bytes on its internal stack. Your device driver should switch to a local stack if it uses extensive stack operations. 2.12 Two Sample Device Drivers The following two examples illustrate a block device driver program and a character device driver program. These examples are provided as guides for writing your own device drivers. However, since device drivers are hardware-dependent, your device drivers will differ. Block Device Driver ; ********************* A Block Device ******************* Title 5.25-inch Disk Driver ; This driver is intended to drive up to four 5.25-inch ; drives hooked to a single disk controller. All standard ; IBM PC formats are supported. FALSE EQU 0 TRUE EQU NOT FALSE ; The I/O port address of the disk controller DISK EQU 0E0H ; DISK+0 ; 1793 Command/Status ; DISK+1 ; 1793 Track ; DISK+2 ; 1793 Sector ; DISK+3 ; 1793 Data ; DISK+4 ; Aux Command/Status ; DISK+5 ; Wait Sync ; Back side select bit BACKBIT EQU 04H ; 5 1/4" select bit SMALBIT EQU 10H ; Double Density bit DDBIT EQU 08H ; Done bit in status register DONEBIT EQU 01H ; Use table below to select head step speed. ; Step times for 5" drives ; are double that shown in the ; Step value 1771 1793 ; ; 0 6ms 3ms ; 1 6ms 6ms ; 2 10ms 10ms ; 3 20ms 15ms ; STPSPD EQU 1 NUMERR EQU ERROUT-ERRIN CR EQU 0DH LF EQU 0AH CODE SEGMENT ASSUME CS:CODE,DS:NOTHING,ES:NOTHING,SS:NOTHING ; ----------------------------------------------------- ; ; Device Header ; DRVDEV LABEL WORD DW -1,-1 DW 0000 ; IBM format-compatible, Block DW STRATEGY DW DRV$IN DRVMAX DB 4 DRVTBL LABEL WORD DW DRV$INIT DW MEDIA$CHK DW GET$BPB DW CMDERR DW DRV$READ DW EXIT DW EXIT DW EXIT DW DRV$WRIT DW DRV$WRIT DW EXIT DW EXIT DW EXIT ; ------------------------------------ ; ; Strategy PTRSAV DD 0 STRATP PROC FAR STRATEGY: MOV WORD PTR [PTRSAV],BX MOV WORD PTR [PTRSAV+2],ES RET STRATP ENDP ; -------------------------------------- ; ; Main Entry CMDLEN = 0 ; Length of this command UNIT = 1 ; Subunit specified CMDC = 2 ; Command Code STATUS = 3 ; Status MEDIA = 13 ; Media Descriptor TRANS = 14 ; Transfer Address COUNT = 18 ; Count of blocks or characters START = 20 ; First block to transfer DRV$IN: PUSH SI PUSH AX PUSH CX PUSH DX PUSH DI PUSH BP PUSH DS PUSH ES PUSH BX LDS BX,[PTRSAV] ; Get pointer to I/O packet MOV AL,BYTE PTR [BX].UNIT ; AL = Unit Code MOV AH,BYTE PTR [BX].MEDIA ; AH = Media Descrip MOV CX,WORD PTR [BX].COUNT ; CX = Count MOV DX,WORD PTR [BX].START ; DX = Start Sector PUSH AX MOV AL,BYTE PTR [BX].CMDC ; Command code CMP AL,15 JA CMDERRP ; Bad command CBW SHL AX,1 ; 2 times command = ; word table index MOV SI,OFFSET DRVTBL ADD SI,AX ; Index into table POP AX ; Get back media ; and unit LES DI,DWORD PTR [BX].TRANS ; ES:DI = Transfer ; Address PUSH CS POP DS ASSUME DS:CODE JMP WORD PTR [SI] ; GO DO COMMAND ; ---------------------------------------------------------- ; ; EXIT - All Routines return through this path ; ASSUME DS:NOTHING CMDERRP: POP AX ; Clean stack CMDERR: MOV AL,3 ; Unknown command error JMP SHORT ERR$EXIT ERR$CNT:LDS BX,[PTRSAV] SUB WORD PTR [BX].COUNT,CX ; # OF SUCCESS. I/Os ERR$EXIT: ; AL has error code MOV AH,10000001B ; Mark error return JMP SHORT ERR1 EXITP PROC FAR EXIT: MOV AH,00000001B ERR1: LDS BX,[PTRSAV] MOV WORD PTR [BX].STATUS,AX ; Mark Operation CompleteE POP BX POP ES POP DS POP BP POP DI POP DX POP CX POP AX POP SI RET ; Restore REGS and return EXITP ENDP CURDRV DB -1 TRKTAB DB -1,-1,-1,-1 SECCNT DW 0 DRVLIM = 8 ; Number of sectors on device SECLIM = 13 ; Maximum Sector HDLIM = 15 ; Maximum Head ; WARNING - preserve order of drive and curhd! DRIVE DB 0 ; Physical Drive Code CURHD DB 0 ; Current Head CURSEC DB 0 ; Current Sector CURTRK DW 0 ; Current Track ; MEDIA$CHK: ; Always indicates Don't know ASSUME DS:CODE TEST AH,00000100B ; Test if Media Removable JZ MEDIA$EXT XOR DI,DI ; Say I Don't know MEDIA$EXT: LDS BX,[PTRSAV] MOV WORD PTR [BX].TRANS,DI JMP EXIT BUILD$BPB: ASSUME DS:CODE MOV AH,BYTE PTR ES:[DI] ; Get FAT ID Byte CALL BUILDBP ; Translate SETBPB: LDS BX,[PTRSAV] MOV [BX].MEDIA,AH MOV [BX].COUNT,DI MOV [BX].COUNT+2,CS JMP EXIT BUILDBP: ASSUME DS:NOTHING ; AH is media byte on entry ; DI points to correct BPB on return PUSH AX PUSH CX PUSH DX PUSH BX MOV CL,AH ; Save Media AND CL,0F8H ; Normalize CMP CL,0F8H ; Compare with Good Media Byte JZ GOODID MOV AH,0FEH ; Default to 8-sector, ; Single-sided GOODID: MOV AL,1 ; Set number of FAT sectors MOV BX,64*256+8 ; Set Dir Entries and Sector Max MOV CX,40*8 ; Set Size of Drive MOV DX,01*256+1 ; Set Head Limit & Sec/All Unit MOV DI,OFFSET DRVBPB TEST AH,00000010B ; Test for 8 OR 9 Sectors JNZ HAS8 ; NZ = has 8 sectors INC AL ; Inc Number of FAT sectors INC BL ; Inc Sector Max ADD CX,40 ; Increase Size HAS8: TEST AH,00000001B ; Test for 1 or 2 Heads JZ HAS1 ; Z = 1 Head ADD CX,CX ; Double Size of Disk MOV BH,112 ; Increase # of Dir Entries INC DH ; Inc Sec/All Unit INC DL ; Inc Head Limit HAS1: MOV BYTE PTR [DI].2,DH MOV BYTE PTR [DI].6,BH MOV WORD PTR [DI].8,CX MOV BYTE PTR [DI].10,AH MOV BYTE PTR [DI].11,AL MOV BYTE PTR [DI].13,BL MOV BYTE PTR [DI].15,DL POP BX POP DX POP CX POP AX RET ; ---------------------------------------------------------- ; ; Disk I/O Handlers ; ; ENTRY: ; AL = Drive Number (0-3) ; AH = Media Descriptor ; CX = Sector Count ; DX = First Sector ; DS = CS ; ES:DI = Transfer Address ; EXIT: ; IF Successful Carry Flag = 0 ; ELSE CF=1 AND AL contains (MS-DOS) Error Code, CX # sectors NOT transferred DRV$READ: ASSUME DS:CODE JCXZ DSKOK CALL SETUP JC DSK$IO CALL DISKRD JMP SHORT DSK$IO DRV$WRIT: ASSUME DS:CODE JCXZ DSKOK CALL SETUP JC DSK$IO CALL DISKWRT ASSUME DS:NOTHING DSK$IO: JNC DSKOK JMP ERR$CNT DSKOK: JMP EXIT SETUP: ASSUME DS:CODE ; Input same as above ; On output ; ES:DI = Trans addr ; DS:BX Points to BPB ; Carry set if error (AL is error code (MS-DOS)) ; else ; [DRIVE] = Drive number (0-3) ; [SECCNT] = Sectors to transfer ; [CURSEC] = Sector number of start of I/O ; [CURHD] = Head number of start of I/O ; Set ; [CURTRK] = Track # of start of I/O ; Seek performed ; All other registers destroyed XCHG BX,DI ; ES:BX = Transfer Address CALL BUILDBP ; DS:DI = PTR to B.P.B MOV SI,CX ADD SI,DX CMP SI,WORD PTR [DI].DRVLIM ; Compare Against Drive Max JBE INRANGE MOV AL,8 STC RET INRANGE: MOV [DRIVE],AL MOV [SECCNT],CX ; Save Sector Count XCHG AX,DX ; Set Up Logical Sector ; For Divide XOR DX,DX DIV WORD PTR [DI].SECLIM ; Divide by Sec per Track INC DL MOV [CURSEC],DL ; Save Current Sector MOV CX,WORD PTR [DI].HDLIM ; Get Number of Heads XOR DX,DX ; Divide Tracks by Heads per Cylinder DIV CX MOV [CURHD],DL ; Save Current Head MOV [CURTRK],AX ; Save Current Track SEEK: PUSH BX ; Xaddr PUSH DI ; BPB pointer CALL CHKNEW ; Unload head if change drives CALL DRIVESEL MOV BL,[DRIVE] XOR BH,BH ; BX drive index ADD BX,OFFSET TRKTAB ; Get current track MOV AX,[CURTRK] MOV DL,AL ; Save desired track XCHG AL,DS:[BX] ; Make desired track current OUT DISK+1,AL ; Tell Controller current track CMP AL,DL ; At correct track? JZ SEEKRET ; Done if yes MOV BH,2 ; Seek retry count CMP AL,-1 ; Position Known? JNZ NOHOME ; If not home head TRYSK: CALL HOME JC SEEKERR NOHOME: MOV AL,DL OUT DISK+3,AL ; Desired track MOV AL,1CH+STPSPD ; Seek CALL DCOM AND AL,98H ; Accept not rdy, seek, & CRC errors JZ SEEKRET JS SEEKERR ; No retries if not ready DEC BH JNZ TRYSK SEEKERR: MOV BL,[DRIVE] XOR BH,BH ; BX drive index ADD BX,OFFSET TRKTAB ; Get current track MOV BYTE PTR DS:[BX],-1 ; Make current track ; unknown CALL GETERRCD MOV CX,[SECCNT] ; Nothing transferred POP BX ; BPB pointer POP DI ; Xaddr RET SEEKRET: POP BX ; BPB pointer POP DI ; Xaddr CLC RET ; --------------------------------------------- ; ; Read ; DISKRD: ASSUME DS:CODE MOV CX,[SECCNT] RDLP: CALL PRESET PUSH BX MOV BL,10 ; Retry count MOV DX,DISK+3 ; Data port RDAGN: MOV AL,80H ; Read command CLI ; Disable for 1793 OUT DISK,AL ; Output read command MOV BP,DI ; Save address for retry JMP SHORT RLOOPENTRY RLOOP: STOSB RLOOPENTRY: IN AL,DISK+5 ; Wait for DRQ or INTRQ SHR AL,1 IN AL,DX ; Read data JNC RLOOP STI ; Ints OK now CALL GETSTAT AND AL,9CH JZ RDPOP ; Ok MOV DI,BP ; Get back transfer DEC BL JNZ RDAGN CMP AL,10H ; Record not found? JNZ GOT_CODE ; No MOV AL,1 ; Map it GOT_CODE: CALL GETERRCD POP BX RET RDPOP: POP BX LOOP RDLP CLC RET ; --------------------------------------------- ; ; Write ; DISKWRT: ASSUME DS:CODE MOV CX,[SECCNT] MOV SI,DI PUSH ES POP DS ASSUME DS:NOTHING WRLP: CALL PRESET PUSH BX MOV BL,10 ; Retry count MOV DX,DISK+3 ; Data port WRAGN: MOV AL,0A0H ; Write command CLI ; Disable for 1793 OUT DISK,AL ; Output write command MOV BP,SI ; Save address for retry WRLOOP: IN AL,DISK+5 SHR AL,1 LODSB ; Get data OUT DX,AL ; Write data JNC WRLOOP STI ; Ints OK now DEC SI CALL GETSTAT AND AL,0FCH JZ WRPOP ; Ok MOV SI,BP ; Get back transfer DEC BL JNZ WRAGN CALL GETERRCD POP BX RET WRPOP: POP BX LOOP WRLP CLC RET PRESET: ASSUME DS:NOTHING MOV AL,[CURSEC] CMP AL,CS:[BX].SECLIM JBE GOTSEC MOV DH,[CURHD] INC DH CMP DH,CS:[BX].HDLIM JB SETHEAD ; Select new head CALL STEP ; Go on to next track XOR DH,DH ; Select head zero SETHEAD: MOV [CURHD],DH CALL DRIVESEL MOV AL,1 ; First sector MOV [CURSEC],AL ; Reset CURSEC GOTSEC: OUT DISK+2,AL ; Tell controller which sector INC [CURSEC] ; We go on to next sector RET STEP: ASSUME DS:NOTHING MOV AL,58H+STPSPD ; Step in w/ update, no verify CALL DCOM PUSH BX MOV BL,[DRIVE] XOR BH,BH ; BX drive index ADD BX,OFFSET TRKTAB ; Get current track INC BYTE PTR CS:[BX] ; Next track POP BX RET HOME: ASSUME DS:NOTHING MOV BL,3 TRYHOM: MOV AL,0CH+STPSPD ; Restore with verify CALL DCOM AND AL,98H JZ RET3 JS HOMERR ; No retries if not ready PUSH AX ; Save real error code MOV AL,58H+STPSPD ; Step in w/ update no verify CALL DCOM DEC BL POP AX ; Get back real error code JNZ TRYHOM HOMERR: STC RET3: RET CHKNEW: ASSUME DS:NOTHING MOV AL,[DRIVE] ; Get disk drive number MOV AH,AL XCHG AL,[CURDRV] ; Make new drive current. CMP AL,AH ; Changing drives? JZ RET1 ; No ; If changing drives, unload head so the head load delay ; one-shot will fire again. Do it by seeking to the same ; track with the H bit reset. ; IN AL,DISK+1 ; Get current track number OUT DISK+3,AL ; Make it the track to seek MOV AL,10H ; Seek and unload head DCOM: ASSUME DS:NOTHING OUT DISK,AL PUSH AX AAM ; Delay 10 microseconds POP AX GETSTAT: IN AL,DISK+4 TEST AL,DONEBIT JZ GETSTAT IN AL,DISK RET1: RET DRIVESEL: ASSUME DS:NOTHING ; Select the drive based on current info ; Only AL altered MOV AL,[DRIVE] OR AL,SMALBIT + DDBIT ; 5 1/4" IBM PC disks CMP [CURHD],0 JZ GOTHEAD OR AL,BACKBIT ; Select side 1 GOTHEAD: OUT DISK+4,AL ; Select drive and side RET GETERRCD: ASSUME DS:NOTHING PUSH CX PUSH ES PUSH DI PUSH CS POP ES ; Make ES the local segment MOV CS:[LSTERR],AL ; Terminate list w/ error code MOV CX,NUMERR ; Number of error conditions MOV DI,OFFSET ERRIN ; Point to error conditions REPNE SCASB MOV AL,NUMERR-1[DI] ; Get translation STC ; Flag error condition POP DI POP ES POP CX RET ; and return ; ********************************************************* ; BPB for an IBM floppy disk, Various parameters are ; patched by BUILDBP to reflect the type of Media ; inserted ; This is a 9-sector, single-side BPB DRVBPB: DW 512 ; Physical sector size in bytes DB 1 ; Sectors/allocation unit DW 1 ; Reserved sectors for DOS DB 2 ; # of allocation tables DW 64 ; Number directory entries DW 9*40 ; Number 512-byte sectors DB 11111100B ; Media descriptor DW 2 ; Number of FAT sectors DW 9 ; Sector limit DW 1 ; Head limit INITAB DW DRVBPB ; Up to four units DW DRVBPB DW DRVBPB DW DRVBPB ERRIN: ; DISK ERRORS RETURNED FROM THE CONTROLLER DB 80H ; No response DB 40H ; Write protect DB 20H ; Write Fault DB 10H ; SEEK error DB 8 ; CRC error DB 1 ; Mapped from 10H ; (record not found) on Read LSTERR DB 0 ; All other errors ERROUT: ; RETURNED ERROR CODES CORRESPONDING TO ABOVE DB 2 ; No response DB 0 ; Write Attempt ; On Write-protected disk DB 0AH ; Write fault DB 6 ; SEEK Failure DB 4 ; Bad CRC DB 8 ; Sector not found DB 12 ; General error DRV$INIT: ; ; Determine number of physical drives by reading config.sys ; ASSUME DS:CODE PUSH DS LDS SI,[PTRSAV] ASSUME DS:NOTHING LDS SI,DWORD PTR [SI.COUNT] ; DS:SI points to ; config.sys SCAN_LOOP: CALL SCAN_SWITCH MOV AL,CL OR AL,AL JZ SCAN4 CMP AL,"s" JZ SCAN4 WERROR: POP DS ASSUME DS:CODE MOV DX,OFFSET ERRMSG2 WERROR2: MOV AH,9 INT 21H XOR AX,AX PUSH AX ; No units JMP SHORT ABORT BADNDRV: POP DS MOV DX,OFFSET ERRMSG1 JMP WERROR2 SCAN4: ASSUME DS:NOTHING ; BX is number of floppies OR BX,BX JZ BADNDRV ; User error CMP BX,4 JA BADNDRV ; User error POP DS ASSUME DS:CODE PUSH BX ; Save unit count ABORT: LDS BX,[PTRSAV] ASSUME DS:NOTHING POP AX MOV BYTE PTR [BX].MEDIA,AL ; Unit count MOV [DRVMAX],AL MOV WORD PTR [BX].TRANS,OFFSET DRV$INIT ; SET ; BREAK ADDRESS MOV [BX].TRANS+2,CS MOV WORD PTR [BX].COUNT,OFFSET INITAB ; SET POINTER TO BPB ARRAY MOV [BX].ceOUNT+2,CS JMP EXIT ; ; Put switch in CL, value in BX ; SCAN_SWITCH: XOR BX,BX MOV CX,BX LODSB CMP AL,10 JZ NUMRET CMP AL,"-" JZ GOT_SWITCH CMP AL,"/" JNZ SCAN_SWITCH GOT_SWITCH: CMP BYTE PTR [SI+1],":" JNZ TERROR LODSB OR AL,20H ; Convert to lowercase MOV CL,AL ; Get switch LODSB ; Skip ":" ; ; Get number pointed to by [SI] ; ; Wipes out AX,DX only BX returns number ; GETNUM1:LODSB SUB AL,"0" JB CHKRET CMP AL,9 JA CHKRET CBW XCHG AX,BX MOV DX,10 MUL DX ADD BX,AX JMP GETNUM1 CHKRET: ADD AL,"0" CMP AL," " JBE NUMRET CMP AL,"-" JZ NUMRET CMP AL,"/" JZ NUMRET TERROR: POP DS ; Get rid of return address JMP WERROR NUMRET: DEC SI RET ERRMSG1 DB "SMLDRV: Bad number of drives",13,10,"$" ERRMSG2 DB "SMLDRV: Invalid parameter",13,10,"$" CODE ENDS END Character Device Driver The following program illustrates a character device driver program. ; ******************** A Character Device ******************* Title VT52 Console for 2.0 (IBM) ; :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ; ; IBM Addresses for I/O ; ; :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: CR=13 ; Carriage-Return BACKSP=8 ; BACKSPACE ESC=1BH BRKADR=6CH ; 006C Break vector address ASNMAX=200 ; Size of key assignment buffer CODE SEGMENT BYTE ASSUME CS:CODE,DS:NOTHING,ES:NOTHING ; ---------------------------------------------------------- ; ; C O N - Console Device Driver ; CONDEV: ; Header for device "CON" DW -1,-1 DW 1000000000010011B ; CON IN AND CON OUT DW STRATEGY DW ENTRY DB 'CON ' ; ----------------------------------------------------------- ; ; Command JUMP Tables CONTBL: DW CON$INIT DW EXIT DW EXIT DW CMDERR DW CON$READ DW CON$RDND DW EXIT DW CON$FLSH DW CON$WRIT DW CON$WRIT DW EXIT DW EXIT CMDTABL DB 'A' DW CUU ; cursor up DB 'B' DW CUD ; cursor down DB 'C' DW CUF ; cursor forward DB 'D' DW CUB ; cursor back DB 'H' DW CUH ; cursor position DB 'J' DW ED ; erase display DB 'K' DW EL ; erase line DB 'Y' DW CUP ; cursor position DB 'j' DW PSCP ; save cursor position DB 'k' DW PRCP ; restore cursor position DB 'y' DW RM ; reset mode DB 'x' DW SM ; set mode DB 00 PAGE ; --------------------------------------------------- ; ; Device entry point ; CMDLEN = 0 ; Length of this command UNIT = 1 ; Subunit Specified CMD = 2 ; Command Code STATUS = 3 ; Status MEDIA = 13 ; Media Descriptor TRANS = 14 ; Transfer Address COUNT = 18 ; Count of blocks or characters START = 20 ; First block to transfer PTRSAV DD 0 STRATP PROC FAR STRATEGY: MOV WORD PTR CS:[PTRSAV],BX MOV WORD PTR CS:[PTRSAV+2],ES RET STRATP ENDP ENTRY: PUSH SI PUSH AX PUSH CX PUSH DX PUSH DI PUSH BP PUSH DS PUSH ES PUSH BX LDS BX,CS:[PTRSAV] ; GET POINTER TO I/O PACKET MOV CX,WORD PTR DS:[BX].COUNT ; CX = COUNT MOV AL,BYTE PTR DS:[BX].CMD CBW MOV SI,OFFSET CONTBL ADD SI,AX ADD SI,AX CMP AL,11 JA CMDERR LES DI,DWORD PTR DS:[BX].TRANS PUSH CS POP DS ASSUME DS:CODE JMP WORD PTR [SI] ; GO DO COMMAND PAGE ; ===================================================== ; = ; = Subroutines Shared by Multiple Devices ; = ; ===================================================== ; ----------------------------------------------------- ; ; EXIT - All routines return through this path ; BUS$EXIT: ; Device Busy Exit MOV AH,00000011B JMP SHORT ERR1 CMDERR: MOV AL,3 ; Unknown command error ERR$EXIT: MOV AH,10000001B ; Mark error Return JMP SHORT ERR1 EXITP PROC FAR EXIT: MOV AH,00000001B ERR1: LDS BX,CS:[PTRSAV] MOV WORD PTR [BX].STATUS,AX ; Mark ; Operation Complete POP BX POP ES POP DS POP BP POP DI POP DX POP CX POP AX POP SI RET ; Restore REGS and Return EXITP ENDP ; ----------------------------------------------- ; ; BREAK Key Handling ; BREAK: MOV CS:ALTAH,3 ; Indicate BREAK key Set INTRET: IRET PAGE ; ; WARNING - Variables are very order dependent, so be careful when adding new ones! ; WRAP DB 0 ; 0 = WRAP, 1 = NO WRAP STATE DW S1 MODE DB 3 MAXCOL DB 79 COL DB 0 ROW DB 0 SAVCR DW 0 ALTAH DB 0 ; Special key handling ; ------------------------------------------------------- ; ; CHROUT - Write out Char in AL using current attribute ; ATTRW LABEL WORD ATTR DB 00000111B ; Character Attribute BPAGE DB 0 ; Base Page base dw 0b800h chrout: cmp al,13 jnz trylf mov [col],0 jmp short setit trylf: cmp al,10 jz lf cmp al,7 jnz tryback torom: mov bx,[attrw] and bl,7 mov ah,14 int 10h ret5: ret tryback: cmp al,8 jnz outchr cmp [col],0 jz ret5 dec [col] jmp short setit outchr: mov bx,[attrw] mov cx,1 mov ah,9 int 10h inc [col] mov al,[col] cmp al,[maxcol] jbe setit cmp [wrap],0 jz outchr1 dec [col] ret outchr1: mov [col],0 lf: inc [row] cmp [row],24 jb setit mov [row],23 call scroll setit: mov dh,row mov dl,col xor bh,bh mov ah,2 int 10h ret scroll: call getmod cmp al,2 jz myscroll cmp al,3 jz myscroll mov al,10 jmp torom myscroll: mov bh,[attr] mov bl,' ' mov bp,80 mov ax,[base] mov es,ax mov ds,ax xor di,di mov si,160 mov cx,23*80 cld cmp ax,0b800h jz colorcard rep movsw mov ax,bx mov cx,bp rep stosw sret: push cs pop ds ret colorcard: mov dx,3dah wait2: in al,dx test al,8 jz wait2 mov al,25h mov dx,3d8h out dx,al ; turn off video rep movsw mov ax,bx mov cx,bp rep stosw mov al,29h mov dx,3d8h out dx,al ; turn on video jmp sret GETMOD: MOV AH,15 INT 16 ; get column information MOV BPAGE,BH DEC AH MOV WORD PTR MODE,AX RET ; ------------------------------------------------------ ; ; Console Read Routine ; CON$READ: JCXZ CON$EXIT CON$LOOP: PUSH CX ; Save Count CALL CHRIN ; Get Char in AL POP CX STOSB ; Store Char at ES:DI LOOP CON$LOOP CON$EXIT: JMP EXIT ; --------------------------------------------------------- ; ; Input Single Char into AL ; CHRIN: XOR AX,AX XCHG AL,ALTAH ; Get Character & Zero ALTAH OR AL,AL JNZ KEYRET INAGN: XOR AH,AH INT 22 ALT10: OR AX,AX ; Check for non-key after BREAK JZ INAGN OR AL,AL ; Special case? JNZ KEYRET MOV ALTAH,AH ; Store special key KEYRET: RET ; ---------------------------------------------------------- ; ; Keyboard Non-destructive Read, No Wait ; CON$RDND: MOV AL,[ALTAH] OR AL,AL JNZ RDEXIT RD1: MOV AH,1 INT 22 JZ CONBUS OR AX,AX JNZ RDEXIT MOV AH,0 INT 22 JMP CON$RDND RDEXIT: LDS BX,[PTRSAV] MOV [BX].MEDIA,AL EXVEC: JMP EXIT CONBUS: JMP BUS$EXIT ; ---------------------------------------------------------- ; ; Keyboard Flush Routine ; CON$FLSH: MOV [ALTAH],0 ; Clear out holding buffer PUSH DS XOR BP,BP MOV DS,BP ; Select segment 0 MOV DS:BYTE PTR 41AH,1EH ; Reset KB queue head ; pointer MOV DS:BYTE PTR 41CH,1EH ; Reset tail pointer POP DS JMP EXVEC ; ---------------------------------------------------------- ; ; Console Write Routine ; CON$WRIT: JCXZ EXVEC PUSH CX MOV AH,3 ; Set current cursor position XOR BX,BX INT 16 MOV WORD PTR [COL],DX POP CX CON$LP: MOV AL,ES:[DI] ; Get Char INC DI CALL OUTC ; Output Char LOOP CON$LP ; Repeat until all through JMP EXVEC COUT: STI PUSH DS PUSH CS POP DS CALL OUTC POP DS IRET OUTC: PUSH AX PUSH CX PUSH DX PUSH SI PUSH DI PUSH ES PUSH BP CALL VIDEO POP BP POP ES POP DI POP SI POP DX POP CX POP AX RET ; ---------------------------------------------------------- ; ; Output Single Char in AL to Video Device ; VIDEO: MOV SI,OFFSET STATE JMP [SI] S1: CMP AL,ESC ; Escape sequence? JNZ S1B MOV WORD PTR [SI],OFFSET S2 RET S1B: CALL CHROUT S1A: MOV WORD PTR [STATE],OFFSET S1 RET S2: PUSH AX CALL GETMOD POP AX MOV BX,OFFSET CMDTABL-3 S7A: ADD BX,3 CMP BYTE PTR [BX],0 JZ S1A CMP BYTE PTR [BX],AL JNZ S7A JMP WORD PTR [BX+1] MOVCUR: CMP BYTE PTR [BX],AH JZ SETCUR ADD BYTE PTR [BX],AL SETCUR: MOV DX,WORD PTR COL XOR BX,BX MOV AH,2 INT 16 JMP S1A CUP: MOV WORD PTR [SI],OFFSET CUP1 RET CUP1: SUB AL,32 MOV BYTE PTR [ROW],AL MOV WORD PTR [SI],OFFSET CUP2 RET CUP2: SUB AL,32 MOV BYTE PTR [COL],AL JMP SETCUR SM: MOV WORD PTR [SI],OFFSET S1A RET CUH: MOV WORD PTR COL,0 JMP SETCUR CUF: MOV AH,MAXCOL MOV AL,1 CUF1: MOV BX,OFFSET COL JMP MOVCUR CUB: MOV AX,00FFH JMP CUF1 CUU: MOV AX,00FFH CUU1: MOV BX,OFFSET ROW JMP MOVCUR CUD: MOV AX,23*256+1 JMP CUU1 PSCP: MOV AX,WORD PTR COL MOV SAVCR,AX JMP SETCUR PRCP: MOV AX,SAVCR MOV WORD PTR COL,AX JMP SETCUR ED: CMP BYTE PTR [ROW],24 JAE EL1 MOV CX,WORD PTR COL MOV DH,24 JMP ERASE EL1: MOV BYTE PTR [COL],0 EL: MOV CX,WORD PTR [COL] EL2: MOV DH,CH ERASE: MOV DL,MAXCOL MOV BH,ATTR MOV AX,0600H INT 16 ED3: JMP SETCUR RM: MOV WORD PTR [SI],OFFSET RM1 RET RM1: XOR CX,CX MOV CH,24 JMP EL2 CON$INIT: int 11h and al,00110000b cmp al,00110000b jnz iscolor mov [base],0b000h ; look for bw card iscolor: cmp al,00010000b ; look for 40 col mode ja setbrk mov [mode],0 mov [maxcol],39 setbrk: XOR BX,BX MOV DS,BX MOV BX,BRKADR MOV WORD PTR [BX],OFFSET BREAK MOV WORD PTR [BX+2],CS MOV BX,29H*4 MOV WORD PTR [BX],OFFSET COUT MOV WORD PTR [BX+2],CS LDS BX,CS:[PTRSAV] MOV WORD PTR [BX].TRANS,OFFSET CON$INIT ; SET BREAK ADDRESS MOV [BX].TRANS+2,CS JMP EXIT CODE ENDS END ──────────────────────────────────────────────────────────────────────────── Chapter 3 MS-DOS Technical Information 3.1 Introduction 3.2 MS-DOS Initialization 3.3 The Command Processor 3.4 MS-DOS Disk Allocation 3.5 MS-DOS Disk Directory 3.6 File Allocation Table (FAT) 3.6.1 How to Use the FAT (12-Bit FAT Entries) 3.6.2 How to Use the FAT (16-Bit FAT Entries) 3.7 MS-DOS Standard Disk Formats 3.1 Introduction This chapter describes how MS-DOS initializes and how it allocates disk space for the root directory, the File Allocation Tables (FAT), and the data area. For programmers writing installable device drivers, this chapter explains MS-DOS disk directory entries and File Allocation Tables. At the end of the chapter, Tables 3.1 and 3.2 describe MS-DOS standard formats for floppy disks. 3.2 MS-DOS Initialization MS-DOS initialization consists of several steps. When you reset your computer or turn on its power, the ROM (Read Only Memory) BIOS is invoked and performs hardware checks and initialization. The ROM BIOS then examines drive A for the boot sector. If it locates a boot sector, the ROM BIOS reads it into low memory and gives it control. If it doesn't find the boot sector, the ROM BIOS then looks in the active partition of the hard disk. If it still doesn't find the boot sector, then the ROM BIOS invokes ROM BASIC. On a removable disk (3.5-inch, 5.25-inch, or 8-inch disk), the boot sector is always located on track 0, sector 1, side 0 of the disk. On a hard disk, the boot sector begins on the first sector of the MS-DOS partition. The hard disk boot sector also includes a partition table. This table identifies the active MS-DOS partition and any other partitions, such as an extended MS-DOS partition, on the hard disk. Notice that extended MS-DOS partitions are not bootable. The boot sector then reads the following files, in the order listed: io.sys msdos.sys ────────────────────────────────────────────────────────────────────────── Note Versions of MS-DOS prior to 3.3 required the io.sys file to be contiguous. This is no longer a requirement. ────────────────────────────────────────────────────────────────────────── Next, the system initialization routine SYSINIT loads all of the resident device drivers. Then, it searches for a config.sys file on the boot disk. SYSINIT allocates memory for buffers and files, based on settings in the config.sys file or system default settings. If the config.sys file specifies any installable device drivers, these are installed next. Finally, SYSINIT executes the MS-DOS command processor, command.com. 3.3 The Command Processor The command processor command.com consists of three parts: ■ A resident part resides in memory immediately following msdos.sys and its data area. This part contains routines to process Interrupts 22H (Terminate Process Exit Address), 23H (CONTROL+C Exit Address), and 24H (Critical-Error-Handler Address), as well as a routine to reload the transient part, if needed. All standard MS-DOS error handling is done within this part of command.com. This includes displaying error messages and processing the Abort, Retry, Fail, or Ignore messages. ■ An initialization part follows the resident part. During startup, the initialization part is given control; it contains the processor setup routine in the autoexec.bat file. The initialization part determines the segment address at which programs can be loaded, and because it is no longer needed, is overlaid by the first program that command.com loads. ■ A transient part is loaded at the high end of memory. This part contains all the internal command processors and the batch file processor. The transient part of the command processor produces the system prompt (A>, for example), reads commands from the keyboard (or from batch files), and causes them to be executed. For external commands, the transient part builds a command line and issues Function 4B00H (Load and Execute Program) to load and transfer control to the program. 3.4 MS-DOS Disk Allocation The area on a disk partitioned for use by MS-DOS is formatted as follows: 1. Reserved area──variable size 2. First copy of File Allocation Table──variable size 3. Additional copies of File Allocation Table──variable size (optional) 4. Root directory──variable size 5. File data area Space for a file in the data area is not preallocated. The space is allocated one cluster at a time. A cluster consists of one or more consecutive sectors (the number of sectors in a cluster must be a power of 2); the cluster size is determined at format time. All the clusters for a file are "chained" together in the File Allocation Table, discussed in greater detail in Section 3.6, "File Allocation Table (FAT)." MS-DOS normally keeps a second copy of the FAT for consistency, except in the case of reliable storage such as a virtual RAM disk. Should the disk develop a bad sector in the middle of the first FAT, MS-DOS can use the second. This avoids loss of data due to an unreadable FAT. 3.5 MS-DOS Disk Directory The format utility builds the root directory for all disks. This directory's location on the disk and the maximum number of entries are dependent on the media. Specifications for standard removable-disk formats are outlined later in this chapter. Notice, however, that MS-DOS regards directories, other than the root directory, as files, so there is no limit to the number of files that the subdirectories under the root directory may contain. All directory entries are 32 bytes in length and are in the following format (notice that byte offsets are in hexadecimal): Byte Function ────────────────────────────────────────────────────────────────────────── 0-7 Filename. Eight characters, left-aligned and padded, if necessary, with blanks. The first byte of this field indicates the file status as follows: ╓┌─┌──────────────────┌─────────────────┌────────────────────────────────────╖ Byte Status ────────────────────────────────────────────────────────────────────────── 00H The directory entry has never been used. This is used to limit the length of directory searches, for performance reasons. 05H The first character of the filename contains an E5H character. 2EH The entry is for a directory. If the second byte is also 2EH, the cluster field contains the cluster number of this directory's parent directory (0000H if the parent directory is the root directory). Otherwise, bytes 01H Byte Status ────────────────────────────────────────────────────────────────────────── root directory). Otherwise, bytes 01H through 0AH are all spaces, and the cluster field contains the cluster number of this directory. E5H The file was used, but it has since been erased. Any other character is the first character of a filename. 8-0A Filename extension. 0B File attribute. The attribute byte is mapped as follows ────────────────────────────────────────────────────────────────────────── ╓┌─┌──────────────────┌─────────────────┌────────────────────────────────────╖ Byte Contents ────────────────────────────────────────────────────────────────────────── Byte Contents ────────────────────────────────────────────────────────────────────────── 01H File is marked read-only. An attempt to open the file for writing using Function 3DH (Open Handle) results in an error code being returned. This value can be used in programs along with the other attributes in this list. Attempts to delete the file with Function 13H (Delete File) or Function 41H (Delete Directory Entry) will also fail. 02H Hidden file. The file is excluded from normal directory searches. 04H System file. The file is excluded from normal directory searches. 08H The entry contains the volume label in the first 11 bytes. The entry contains no other usable information Byte Contents ────────────────────────────────────────────────────────────────────────── contains no other usable information (except date and time of creation) and may exist only in the root directory. 10H The entry defines a subdirectory and is excluded from normal directory searches. 20H Archive bit. The bit is set to "on" whenever the file has been written to and closed. Note: The system files (io.sys and msdos.sys) are marked as read-only, hidden, and system files. Files can be marked hidden when they are created. Also, you may change the read-only, hidden, system, and Byte Contents ────────────────────────────────────────────────────────────────────────── read-only, hidden, system, and archive attributes through Function 43H (Get/Set File Attributes). ────────────────────────────────────────────────────────────────────────── ╓┌─┌──────────────────┌──────────────────────────────────────────────────────╖ Byte Function ────────────────────────────────────────────────────────────────────────── 0C-15 Reserved. 16-17 Time the file was created or last updated. The hour, minutes, and seconds are mapped into two bytes as follows (bit 7 on the left, 0 on the right): Offset 17H | H | H | H | H | H | M | M | M | Offset 16H Byte Function ────────────────────────────────────────────────────────────────────────── Offset 16H | M | M | M | S | S | S | S | S | where: H is the binary number of hours (0-23). M is the binary number of minutes (0-59). S is the binary number of two-second increments. 18-19 Date the file was created or last updated. The year, month, and day are mapped into two bytes as follows: Offset 19H | Y | Y | Y | Y | Y | Y | Y | M | Offset 18H | M | M | M | D | D | D | D | D | Byte Function ────────────────────────────────────────────────────────────────────────── | M | M | M | D | D | D | D | D | where: Y is the year, 0-119 (1980-2099). M is the month (1-12). D is the day of the month (1-31). ────────────────────────────────────────────────────────────────────────── Byte Function ────────────────────────────────────────────────────────────────────────── 1A-1B Starting cluster; the number of the first cluster in the file. ■ Notice that the first cluster for data space on all disks is cluster 002. ■ The cluster number is stored with the least significant byte first. ■ For details about converting cluster numbers to logical sector numbers, see Sections 3.6.1 and 3.6.2. 1C-1F File size in bytes. The first word of this four-byte ────────────────────────────────────────────────────────────────────────── 3.6 File Allocation Table (FAT) This section explains how MS-DOS allocates disk space in the data area for a file by using the File Allocation Table to convert the clusters of a file to logical sector numbers. The device driver is then responsible for locating the logical sector on the disk. Programs should use the MS-DOS file management function calls for accessing files. Programs that access the FAT are not guaranteed to be upwardly-compatible with future releases of MS-DOS. The following information is useful to system programmers who wish to write installable device drivers. The File Allocation Table is an array of 12-bit entries (1.5 bytes) for each cluster on the disk. For disks containing more than 4085 clusters, a 16-bit FAT entry is used. The first two FAT entries are reserved; however, the device driver may use the first byte as a FAT ID byte for determining media. For hard disks, the value of this byte is F8H. See Tables 3.1 and 3.2 for the media byte descriptors used for 8-inch, 5.25-inch, and 3.5-inch disks. The third FAT entry, which starts at byte offset 4, begins the mapping of the data area (cluster 002). The operating system does not always sequentially write (to the disk) files in the data area. Instead, the system allocates the data area one cluster at a time, skipping over clusters it has already allocated. The first free cluster following the last cluster allocated for that file is the next cluster allocated, regardless of its physical location on the disk. This permits the most efficient use of disk space, since if you erase old files, you can free clusters, which the operating system can then allocate for new files. Each FAT entry contains three or four hexadecimal characters, depending on whether it is a 12-bit or 16-bit entry: Entry Contents ────────────────────────────────────────────────────────────────────────── (0)000 If the cluster is unused and available. (F)FF7 The cluster has a bad sector in it if it is not part of any cluster chain. MS-DOS will not allocate such a cluster. So for its report, the chkdsk command counts the number of bad clusters, which are not part of any allocation chain. (F)FF8-FFF The last cluster of a file. (X)XXX Any other characters that are the cluster number of the next cluster in the file. The number of the first ────────────────────────────────────────────────────────────────────────── The File Allocation Table always begins on the first sector after the reserved sectors. If the FAT is larger than one sector, the sectors are contiguous. The operating system usually writes two copies of the FAT to preserve data integrity. MS-DOS reads the FAT into one of its buffers, whenever needed (open, read, write, etc.). The operating system also gives this buffer a high priority to keep it in memory as long as possible. 3.6.1 How to Use the FAT (12-Bit FAT Entries) To get the starting cluster of a file, examine its directory entry (in the FAT). Then, to locate each subsequent cluster of the file, follow these steps: 1. Multiply the cluster number just used by 1.5 (each FAT entry is 1.5 bytes in length). 2. The whole part of the product is an offset into the FAT, pointing to the entry that maps the cluster just used. That entry contains the cluster number of the next cluster of the file. 3. Use a MOV instruction to move the word at the calculated FAT offset into a register. 4. If the last cluster used was an even number, keep the low-order 12 bits of the register by using the AND operator with 0FFFH and the register. If the last cluster used was an odd number, keep the high-order 12 bits by using the SHR instruction to shift the register right four bits. 5. If the resultant 12 bits are 0FF8H-0FFFH, the file contains no more clusters. Otherwise, the 12 bits contain the number of the next cluster in the file. To convert the cluster to a logical sector number (relative sector, such as that used by Interrupts 25H and 26H (Absolute Disk Read/Write) and by debug), follow these steps: 1. Subtract two from the cluster number. 2. Multiply the result by the number of sectors per cluster. 3. To this result, add the logical sector number of the beginning of the data area. 3.6.2 How to Use the FAT (16-Bit FAT Entries) To get the starting cluster of a file, examine its directory entry (in the FAT). Then, to find the next file cluster, follow these steps: 1. Multiply the cluster number last used by 2 (each FAT entry is 2 bytes). 2. Use a MOV WORD instruction to move the word at the calculated FAT offset into a register. 3. If the resultant 16 bits are 0FFF8-0FFFH, no more clusters are in the file. Otherwise, the 16 bits contain the number of the next cluster in the file. 3.7 MS-DOS Standard Disk Formats MS-DOS arranges data clusters on a disk to minimize head movement. MS-DOS then allocates all the space on one track (or cylinder) before moving to the next. It uses the sequential sectors on the lowest-numbered head, then all the sectors on the next head, and so on, until it has used all the sectors on all the heads of the track. The size of the MS-DOS partition on a hard disk determines the size of the FAT and root directory. Likewise, the type of floppy disk (tracks per side, sectors per track, etc.) determines how MS-DOS uses the disk. The removable disk formats listed in Tables 3.1 and 3.2 are standard and should be readable in the appropriate standard drive. Table 3.1 MS-DOS Standard Removable-Disk Formats Disk Size in inches 5.25 8 ────────────────────────────────────────────────────────────────────────── WORD no. heads 1 1 2 2 1 2 1 Tracks/side 40 40 40 40 77 77 77 WORD sectors/track 8 9 8 9 26 26 8 WORD bytes/sector 512 512 512 512 128 128 024 BYTE sectors/ cluster 1 1 2 2 4 4 1 WORD reserved sectors 1 1 1 1 1 4 1 Byte no. FATs 2 2 2 2 2 2 2 WORD root directory entries 64 64 112 112 68 68 192 WORD no. sectors 320 360 640 720 2002 2002 616 BYTE media descriptor FE FC FF FD FE FD FE WORD sectors/FAT 1 2 1 2 6 6 2 WORD no. hidden sectors 0 0 0 0 0 0 0 ────────────────────────────────────────────────────────────────────────── Table 3.2 MS-DOS Standard Removable-Disk Formats (High-Density) Disk Size in inches 3.5 or 5.25 3.5 5.25 ────────────────────────────────────────────────────────────────────────── WORD no. heads 1 2 2 2 2 2 ────────────────────────────────────────────────────────────────────────── Tracks/side 80 80 80 80 80 80 WORD sectors/track 8 9 8 9 18 15 WORD bytes/sector 512 512 512 512 512 512 BYTE sectors/cluster 2 2 2 2 1 1 WORD reserved sectors 1 1 1 1 1 1 BYTE no. FATs 2 2 2 2 2 2 WORD root dir entries 112 112 112 112 224 224 WORD no. sectors 640 720 1280 1440 2880 2400 BYTE media descriptor FA FC FB F9 F0 F9 WORD sectors/FAT 1 2 2 3 9 7 WORD no. hidden sectors 0 0 0 0 0 0 ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Chapter 4 MS-DOS Control Blocks and Work Areas 4.1 Introduction 4.2 Typical Contents of an MS-DOS Memory Map 4.3 The MS-DOS Program Segment 4.1 Introduction This chapter describes a typical MS-DOS memory map and explains how a program is loaded into memory. It also describes the structure of an MS-DOS program segment and the contents of segment registers for .exe and .com program files. 4.2 Typical Contents of an MS-DOS Memory Map A typical MS-DOS memory map contains the following information: ┌─────────────────────────────────────────────────────┐ │ ROM and Video Buffers │ ├─────────────────────────────────────────────────────┤ │ Transient Part of COMMAND.COM │ ├─────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ │ │ Transient Program Area │ ├─────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ │ │ External Commands and Utilities │ │ │ ├─────────────────────────────────────────────────────┤ │ Resident Part of COMMAND.COM │ ├─────────────────────────────────────────────────────┤ │ MS-DOS buffers, control areas, & installed drivers │ ├─────────────────────────────────────────────────────┤ │ │ │ MSDOS.SYS │ ├─────────────────────────────────────────────────────┤ │ IO.SYS and resident device drivers │ ├─────────────────────────────────────────────────────┤ │ Interrupt Vectors │ 0 └─────────────────────────────────────────────────────┘ During system initialization, MS-DOS loads the io.sys and msdos.sys files into low memory (Notice that in MS-DOS 4.0, the msdos.sys file is not required to be written contiguously to the disk). The io.sys system file is the MS-DOS interface to hardware. The msdos.sys system file includes MS-DOS interrupt handlers and service routines (Interrupt 21H functions). Next, the system initialization routine loads the resident and installable device drivers. Above the installable device drivers, MS-DOS writes the resident part of command.com. This part includes interrupt handlers for Interrupts 22H (Terminate Process Exit Address), 23H (CONTROL+C Handler Address), 24H (Critical-Error-Handler Address) and code to reload the transient part. The transient part of command.com is reloaded into high memory. It includes the command interpreter, the internal MS-DOS commands, and the batch processor. External command and utility (.com and .exe) files are loaded into the transient program area. MS-DOS also allocates 256 bytes of user stack used with .com files. User memory is allocated from the lowest end of available memory that fulfills the allocation request. 4.3 The MS-DOS Program Segment When you type an external command or execute a program through Function 4B00H or 4B03H (Load and Execute Program or Overlay, also called EXEC), MS-DOS determines the lowest available free memory address to use as the start of the program. The memory starting at this address is called the Program Segment. The EXEC system call sets up the first 256 bytes of the Program Segment for the program being loaded into memory. The program is then loaded following this block. A .exe file with minalloc and maxalloc both set to zero is loaded as high as possible. At offset 0 within the Program Segment, MS-DOS builds the Program Segment Prefix control block. The program returns from EXEC by one of five methods: ■ By issuing an Interrupt 21H with AH=4CH (End Process) ■ By issuing an Interrupt 21H with AH=31H (Keep Process) ■ By a long jump to offset 0 in the Program Segment Prefix ■ By issuing an Interrupt 20H (Progam Terminate) with CS:0 pointing at the PSP ■ By issuing an Interrupt 21H with register AH=0 and with CS:0 pointing at the PSP ────────────────────────────────────────────────────────────────────────── Note The first two methods are preferred for functionality, compatibility, and efficiency in future versions of MS-DOS. ────────────────────────────────────────────────────────────────────────── All five methods transfer control to the program that issued the EXEC call. The first two methods return a completion code. They also restore the addresses of Interrupts 22H, 23H, and 24H (Terminate Process Exit Address, CONTROL+C Handler Address, and Critical-Error-Handler Address) from the values saved in the Program Segment Prefix of the terminating program. Control then passes to the terminate address. If a program returns to command.com, control transfers to the resident portion. If the program is a batch file (in process), it continues. Otherwise, command.com performs a checksum on the transient part, reloads it if necessary, issues the system prompt, and waits for you to type another command. When a program receives control, the following conditions are in effect: For All Programs: ■ The segment address of the passed environment is at offset 2CH in the Program Segment Prefix. ■ The environment is a series of ASCII strings (totaling less than 32K) in the form: NAME=parameter ■ A byte of zeros terminates each string, and another byte of zeros terminates the set of strings. Following the last byte of zeros is a set of initial arguments that the operating system passes to a program. This set of arguments contains a word count followed by an ASCII string. If the file is in the current directory, the ASCII string contains the drive and pathname of the executable program as passed to the EXEC function call. If the file is not in the current directory, EXEC concatenates the name of the file with the name of the path. Programs may use this area to determine where the program was loaded. ■ The environment built by the command processor contains at least a comspec=string (the parameters on comspec define the path that MS-DOS uses to locate command.com on the disk). The last path and prompt commands issued are also in the environment, along with any environment strings you have defined with the MS-DOS set command. ■ EXEC passes a copy of the invoking process environment. If your application uses a "keep process" concept, you should be aware that the copy of the environment passed to you is static. That is, it will not change even if you issue subsequent set, path, or prompt commands. Conversely, any modification of the passed environment by the application is not reflected in the parent process environment. For instance, a program cannot change the MS-DOS environment values as the set command does. ■ The Disk Transfer Address (DTA) is set to 80H (default DTA in the Program Segment Prefix). The Program Segment Prefix contains file control blocks at 5CH and 6CH. MS-DOS formats these blocks using the first two parameters that you typed when entering the command. If either parameter contained a pathname, then the corresponding FCB contains only the valid drive number. The filename field is not valid. ■ An unformatted parameter area at 81H contains all the characters typed after the command (including leading and embedded delimiters), with the byte at 80H set to the number of characters. If you type <, >, or parameters on the command line, they do not appear in this area (nor the filenames associated with them). Redirection of standard input and output is transparent to applications. ■ Register AX indicates whether the drive specifiers (entered with the first two parameters) are valid, as follows: AL=FF if the first parameter contained an invalid drive specifier (otherwise AL=00) AH=FF if the second parameter contained an invalid drive specifier (otherwise AH=00) ■ Offset 2 (one word) contains the segment address of the first byte of unavailable memory. Programs must not modify addresses beyond this point unless these addresses were obtained by allocating memory via Function 48H (Allocate Memory). For Executable (.exe) Programs: ■ DS and ES registers point to the Program Segment Prefix. ■ CS,IP,SS, and SP registers contain the values that Microsoft link sets in the .exe image. For Executable (.com) Programs: ■ All four segment registers contain the segment address of the initial allocation block that starts with the Program Segment Prefix control block. ■ .com programs allocate all of user memory. If the program invokes another program through Function 4B00H or 4B03H (EXEC), it must first free some memory through Function 4AH (Set Block) to provide space for the program being executed. ■ The Instruction Pointer (IP) is set to 100H. ■ The Stack Pointer register is set to the end of the program's segment. ■ A .com program places a word of zeros on top of the stack. Then, by doing a RET instruction last, your program can exit to command.com. This method assumes, however, that you have maintained your stack and code segments. Figure 4.1 illustrates the format of the Program Segment Prefix. All offsets are in hexadecimal. (Offsets in Hex) 0 ┌─────────────┬─────────────┬─────────────────────────────┐ │ │ End of │ │ │ INT 20H │ alloc. │ Reserved │ │ │ block │ 04H │ 8 ├─────────────┼─────────────┴──────────┬──────────────────┤ │ │ Terminate address │ CONTROL+C exit │ │ Reserved │ (IP, CS) │ address (IP) │ │ │ │ │ 10├────────────┬┴────────────────────────┼──────────────────┤ │CONTROL+C │ Hard error exit address │ │ │exit │ (IP, CS) │ │ │address (CS)│ │ │ ├────────────┴─────────────────────────┘ │ │ │ │ Used by MS-DOS │ │ │ │ 5CH │ │ │ ├─────────────────────────────────────────────────────────┤ │ │ │ Formatted Parameter Area 1 formatted as standard │ │ unopened FCB 6CH │ ├─────────────────────────────────────────────────────────┤ │ │ │ Formatted Parameter Area 2 formatted as standard │ │ unopened FCB (overlaid if FCB at 5CH is opened) │ 80├─────────────────────────────────────────────────────────┤ │ Unformatted Parameter Area │ │ (default Disk Transfer Area) │ │ Initially contains command invocation line. │ └─────────────────────────────────────────────────────────┘ 100 Figure 4.1 Program Segment Prefix ────────────────────────────────────────────────────────────────────────── Important Programs must not alter any part of the Program Segment Prefix below offset 5CH. ────────────────────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────────────────────── Chapter 5 National Language Support 5.1 Introduction 5.2 National Language Support Calls 5.3 Font Files 5.3.1 Font File Structure 5.1 Introduction National language support for this version of MS-DOS 4.0 includes these major features: ■ Country-dependent information ■ Support for national keyboard layouts ■ Programming interfaces for national language support ■ Utility commands Country-dependent information is available on a per-country basis and includes the following: ■ Time, date, and currency ■ Lowercase-to-uppercase character-conversion tables ■ Collating sequence for character sorting ■ Valid single-byte characters used in filenames Selectable keyboard support for different keyboard layouts is provided. The MS-DOS 4.0 programming interfaces for national language support allow applications to use the country-dependent information just described. To access this information, applications do not need to change the current country code of the system. Utility commands allow the user to select the keyboard layout and system country code. This version of MS-DOS does not support right-to-left national languages. 5.2 National Language Support Calls The following function calls allow an application to tailor its operation to the current country code and to accept or change the current code page. A country code defines the country in which you live or work. MS-DOS uses this code to prepare and assign default code pages for your system. A code page is a table that defines the character set you are using. A character set is a country-specific or language-specific group of characters that are translated from the code page table and displayed on your screen or printer. Each code page character set contains 256 characters. The following function calls are also used by MS-DOS 4.0 to support the National Language requirements: ■ Function 440CH (Generic IOCtl) ── supports code page switching on a per-device basis. ■ Function 65H (Get Extended Country Information) ── returns standard country information and points to related case-map or collating tables. ■ Function 66H (Get/Set Global Code Page) ── gets or sets the code page used by the kernel and by all devices. These functions support access to country-dependent information, all of which resides in one file named country.sys. 5.3 Font Files Font files, also called code page information files, contain the images of code page character sets for use by display or printer devices. These font files are identified by a filename extension of .cpi. Four font files are included with MS-DOS 4.0: Font file Supported device ────────────────────────────────────────────────────────────────────────── ega.cpi Color console used with an EGA card lcd.cpi Liquid crystal display 4201.cpi IBM 4201 Proprinter family and IBM 4202 Proprinter printers 4208.cpi IBM 4207 Proprinter X24 and IBM 4208 Proprinter XL24 printers 5202.cpi IBM 5202 Quietwriter III printer ────────────────────────────────────────────────────────────────────────── 5.3.1 Font File Structure The contents of printer or display font files are structured as follows: ┌──────────────────────────────────────┐ │ 23-BYTE File Header │ ├──────────────────────────────────────┤ │ WORD Information Header │ ├──────────────────────────────────────┤ │ 28-BYTE Code Page Entry Header(s) │ ├──────────────────────────────────────┤ │ Variable size Font Data Block(s) │ ├──────────────────────────────────────┤ │ 150-BYTE Copyright Notice │ └──────────────────────────────────────┘ Figure 5.1 Font File Structure The first code page entry header immediately follows the information header. The copyright notice is always at the end of the file. Between these, the file consists of arbitrarily intermingled code page entry headers and font data blocks. The font file fields are described in the following sections. File Header Each file must begin with a file header. There is only one of these headers per file. This header identifies the file as a valid font file and has the following format: Length Parameter ────────────────────────────────────────────────────────────────────────── 8 BYTES File tag 8 BYTES Reserved WORD Number of pointers BYTE Type of pointer 2 WORDS Offset ────────────────────────────────────────────────────────────────────────── where: File tag begins with the byte 0FFH and is followed by the seven-byte string "font." Reserved is eight bytes of zeros. Number of pointers is the number of information pointers in the header. For MS-DOS 4.0, the value of this word should be 1. Type of pointer is the type of information pointers in the header. For MS-DOS 4.0, the value of this word should be 1. Offset is the offset, in bytes, from the beginning of the file to the information header. Information Header The information header begins at the offset given in the file header. It describes how many code pages are contained in the font file. The format of this one-word information header is: Length Parameter ────────────────────────────────────────────────────────────────────────── WORD Number of code pages ────────────────────────────────────────────────────────────────────────── where: Number of code pages is the number of code page entries in the file. Code Page Entry Header The number of code page entries in a font file is defined in the preceding section, "Information Header." For each code page in the font file, there is a code page entry header that gives general information about that code page entry in the file. The header has the following format: Length Parameter ────────────────────────────────────────────────────────────────────────── WORD Length 2 WORDS Pointer WORD Device type 8 BYTES Device subtype WORD Code page ID 3 WORDS Reserved 2 WORDS Offset ────────────────────────────────────────────────────────────────────────── where: Length is the size of the code page entry header. Since this header is a fixed size, it can be used for testing if the font file has been read in correctly. Pointer is a two-word pointer to the next code page entry header. The last header will point to nothing and will have a value of 0,0. Device type is 1 if the device is a raster display, or 2 if the device is a printer. Device subtype names the type of display or printer. This field also determines the name of the font file. For example, if the subtype is "EGA," the font file name is ega.cpi Code page ID defines a valid three-digit code page identification number. Valid code page numbers are 437, 850, 860, 863, and 865. Reserved is three words of zeros. Offset is a double-word pointer to the font data block associated with this code page and described in the next section. Font Data Block The Font Data Block consists of the following fields: ┌─────────────────────────────────────────┐ │ 6-BYTE Font Data Header │ ├─────────────────────────────────────────┤ │ Variable length Font Description(s) │ └─────────────────────────────────────────┘ The code page of a font data block is specified by the code page entry header whose Offset field points to that font data block. The device type contained in this code page entry header determines whether the font description(s) should be interpreted as raster-style (display) fonts or escape code sequences for particular downloadable device (printer) fonts. The Font Data Header, the Display Font Description, and the Printer Font Description fields are described in the following sections. Font Data Header: The Font Data Header indicates how many font descriptions exist for the current code page. This header has the following fields: Length Parameter ────────────────────────────────────────────────────────────────────────── WORD Reserved WORD Number of fonts WORD Length of font data ────────────────────────────────────────────────────────────────────────── where: Reserved must be 1. Number of fonts specifies the number of fonts (font descriptions) that immediately follow this font data header. These font descriptions are all associated with the font data block's code page. For printer devices, the number of fonts must be equal to one. Length of font data is equal to the sum of the sizes (in bytes) of the font descriptions, as described in the next two sections. Display Font Description: Each font description for a display device begins with a header that specifies the raster dimensions of each character in the font and the number of characters in the font. This is followed by the raster bitmaps for each character. The actual fields are: Length Parameter ────────────────────────────────────────────────────────────────────────── BYTE Height BYTE Width BYTE Relative height BYTE Relative width WORD Number of characters Variable Bitmap ────────────────────────────────────────────────────────────────────────── where: Height is the number of rows in pixels that this character occupies on the screen. Width is the number of columns in pixels that this character occupies on the screen. Relative height is part of the aspect ratio. This is currently unused (zero). Relative width is part of the aspect ratio. This is currently unused (zero). Number of characters is the number of characters that are defined in the bitmap immediately following this header. Normally, the entire ASCII character set is defined, so that this value is usually 256. Bitmap is a sequence of bitmaps, one for each character in the font. Each character bitmap is a packed array of bits organized in rows by columns, starting at the upper left corner of the character's image. Since all current display fonts are eight bits wide, the number of bytes needed to encode this packed array is simply equal to the square area of a character in the font divided by 8 (the number of bits per byte). The total length of the display font description is six bytes plus the product of the number of characters in the descriptions and the number of bytes needed to encode a character bitmap. Printer Font Description: There are two formats for printer font descriptions. These vary only in the number of control sequences present in the font description. Unlike the display font description, the number of bytes in the printer font description cannot be directly determined. Instead, the size of the printer font description must be calculated from the font header's length value. As a result, only one printer font description can be contained in a given font data block (otherwise, the point at which the first ended and the second printer font description began could not be determined). The format for the printer font desription is: Length Parameter ────────────────────────────────────────────────────────────────────────── WORD Selection type WORD Control sequence length Variable Control sequence data Variable Downloadable font data ────────────────────────────────────────────────────────────────────────── where: Selection type is either 1 or 2. It identifies which of the two formats for the printer font description is being used. These existing printer files use the following selection types: Selection type Printer font file ─────────────────────────────────────────────────────────────────────── 1 4201.cpi 2 4208.cpi 2 5202.cpi ─────────────────────────────────────────────────────────────────────── Control sequence length is the number of bytes the control sequence data field takes. This length must always be less than 31 (bytes). Control sequence data is used for initializing the printer with this code page. The size of this field is defined in the control sequence length field. If the selection type field is 2, this control sequence information consists of a single escape sequence that selects the font for this code page (this font may have been downloaded). If the selection type field is 1, this control sequence information is further divided into two escape sequences. In this case, the control sequence data field consists of: Length Parameter ─────────────────────────────────────────────────────────────────────── BYTE Hardware sequence length Variable Hardware sequence BYTE Downloadable sequence length Variable Downloadable sequence ─────────────────────────────────────────────────────────────────────── where: Hardware sequence length is the number of bytes contained in the hardware sequence. Hardware sequence is the escape sequence that selects the hardware (default) font of the printer. Downloadable sequence length is the number of bytes contained in the downloadable sequence. Downloadable sequence is the escape sequence that selects the downloaded font currently resident in the printer. Notice that the total number of bytes in these subfields must be equal to the number of bytes given by the control sequence length field in the printer font description. Downloadable font data consists of the escape sequence required to download the font description. This escape sequence is highly printer specific. The number of bytes in it is determined by subtracting the size of the initial portion of the printer font description from the Length field of the font data block. Since the 4208 and 5202 printers have hardware support for code pages, they do not need any font data to be downloaded. Therefore, this field is nonexistent in those font files. ──────────────────────────────────────────────────────────────────────────── Chapter 6 .Exe File Structure and Loading 6.1 Introduction 6.2 Format of a File Header 6.3 The Relocation Table 6.1 Introduction ────────────────────────────────────────────────────────────────────────── Note This chapter describes .exe file structure and loading procedures for systems that use a version of MS-DOS earlier than 2.0. For MS-DOS versions 2.0 and later, use Function B00H (Load and Execute Program) to load (or load and execute) a .exe file. ────────────────────────────────────────────────────────────────────────── The .exe files produced by link consist of two parts: ■ Control and relocation information ■ The load module The control and relocation information is at the beginning of the file in an area called the header. Immediately following this header is the load module. 6.2 Format of a File Header The header is formatted as follows (notice that offsets are in hexadecimal): ╓┌─┌──────────────────┌──────────────────────────────────────────────────────╖ Offset Contents ────────────────────────────────────────────────────────────────────────── 0-1 Must contain 4DH, 5AH. 2-3 Number of bytes contained in last page; useful for reading overlays. 4-5 Size of the file in 512-byte pages, including the header. 6-7 Number of relocation entries in table. 8-9 Size of the header in 16-byte paragraphs. Used to Offset Contents ────────────────────────────────────────────────────────────────────────── 8-9 Size of the header in 16-byte paragraphs. Used to locate the beginning of the load module in the file. AH-BH Minimum number of 16-byte paragraphs required above the end of the loaded program. CH-DH Maximum number of 16-byte paragraphs required above the end of the loaded program. If both minalloc and maxalloc are 0, the program is loaded as high as possible. EH-FH Initial value to be loaded into stack segment before starting program execution. Must be adjusted by relocation. 10-11 Value to be loaded into the SP register before starting program execution. 12-13 Negative sum of all the words in the file. Offset Contents ────────────────────────────────────────────────────────────────────────── 12-13 Negative sum of all the words in the file. 14-15 Initial value to be loaded into the IP register before starting program execution. 16-17 Initial value to be loaded into the CS register before starting program execution. Must be adjusted by relocation. 18-19 Relative byte offset from beginning of run file to relocation table. 1AH-1BH The number of the overlay as generated by link. ────────────────────────────────────────────────────────────────────────── 6.3 The Relocation Table The relocation table that follows the formatted area above consists of a variable number of relocation items. Each relocation item contains two fields: a two-byte offset value, followed by a two-byte segment value. These two fields contain the offset into a word's load module. This item requires modification before the module is given control. The following steps describe this process: 1. The formatted part of the header is read into memory. Its size is 1BH. 2. MS-DOS allocates a portion of memory depending on the size of the load module and the allocation numbers (AH-BH and CH-DH). MS-DOS then attempts to allocate 0FFFH paragraphs. This attempt always fails and returns the size of the largest free block. If this block is smaller than minalloc and loadsize, there is no memory error. But if this block is larger than maxalloc and loadsize, MS-DOS allocates (maxalloc + loadsize). Otherwise, it allocates the largest free block of memory. 3. A Program Segment Prefix is built in the lowest part of the allocated memory. 4. MS-DOS calculates the load module size (using offsets 4-5 and 8-9) by subtracting the header size from the file size. The actual size is adjusted down based on the contents of offsets 2-3. The operating system determines (based on the setting of the high/low load switch) an appropriate segment, called the start segment, where it loads the load module. 5. The load module is read into memory beginning with the start segment. 6. The items in the relocation table are read into a work area. 7. MS-DOS adds the segment value of each relocation table item to the start segment value. This calculated segment, plus offset, points to the module to which the start segment value is added. The result is then placed back into the word in the load module. 8. Once all relocation items have been processed, the operating system sets the SS and SP registers, using the values in the header. MS-DOS then adds the start segment value to SS and sets the ES and DS registers to the segment address of the Program Segment Prefix. The start segment value is then added to the header CS register value. The result, along with the header IP value, is the initial CS:IP to transfer to before starting execution of the program. ──────────────────────────────────────────────────────────────────────────── Chapter 7 Relocatable Object Module Formats 7.1 Introduction 7.1.1 Definition of Terms 7.2 Module Identification and Attributes 7.2.1 Segment Definition 7.2.2 Addressing a Segment 7.2.3 Symbol Definition 7.2.4 Indices 7.3 Conceptual Framework for Fixups 7.3.1 Self-Relative Fixup 7.3.2 Segment-Relative Fixup 7.4 Record Sequence 7.5 Introducing the Record Formats 7.5.1 Sample Record Format (SAMREC) 7.5.2 T-Module Header Record (THEADR) 7.5.3 L-Module Header Record (LHEADR) 7.5.4 List of Names Record (LNAMES) 7.5.5 Segment Definition Record (SEGDEF) 7.5.6 Group Definition Record (GRPDEF) 7.5.7 Public Names Definition Record (PUBDEF) 7.5.8 Communal Names Definition Record (COMDEF) 7.5.9 Local Symbols Record (LOCSYM) 7.5.10 External Names Definition Record (EXTDEF) 7.5.11 Line Numbers Record (LINNUM) 7.5.12 Logical Enumerated Data Record (LEDATA) 7.5.13 Logical Iterated Data Record (LIDATA) 7.5.14 Fixup Record (FIXUPP) 7.5.15 Module End Record (MODEND) 7.5.16 Comment Record (COMENT) 7.6 Microsoft Type Representations for Communal Variables 7.1 Introduction This chapter presents the object record formats that define the relocatable object language for the 8086, 80186, and 80286 microprocessors. The 8086 object language is the output of all language translators that have an 8086 processor and that will be linked by the Microsoft linker. The 8086 object language is used for input and output for object language processors such as linkers and librarians, and in the XENIX, PC-DOS, and MS-DOS operating systems. The 8086 object module formats let you specify relocatable memory images that may be linked together. These formats also allow efficient use of the memory mapping facilities of the 8086 family of microprocessors. The following table lists the record formats that Microsoft supports. Their abbreviations appear in parentheses. Each is described in this chapter. Table 7.1 Object Module Record Formats Symbol Definition Records ────────────────────────────────────────────────────────────────────────── Public Names Definition Record (PUBDEF) Communal Names Definition Record (COMDEF) Local Symbols Record (LOCSYM) External Names Definition Record (EXTDEF) Line Numbers Record (LINNUM) Data Records Logical Enumerated Data Record (LEDATA) Logical Iterated Data Record (LIDATA) T-Module Header Record (THEADR) L-Module Header Record (LHEADR) List of Names Record (LNAMES) Segment Definition Record (SEGDEF) Group Definition Record (GRPDEF) Fixup Record (FIXUPP) Module End Record (MODEND) Comment Record (COMENT) ────────────────────────────────────────────────────────────────────────── ────────────────────────────────────────────────────────────────────────── Note If an object module contains any undefined values, the behavior of the Microsoft linker is undefined. All undefined values should be considered reserved by Microsoft for future use. ────────────────────────────────────────────────────────────────────────── 7.1.1 Definition of Terms The following terms are fundamental to 8086 relocation and linkage: OMF - Object Module Formats MAS - Memory Address Space The 8086 MAS is one megabyte (1,048,576 bytes). Notice that the MAS is distinguished from actual memory, which may occupy only a portion of the MAS. Module A module is an "inseparable" collection of object code and other information produced by a translator. T-Module A T-module is a module created by a translator, such as Pascal or FORTRAN. The following restrictions apply to object modules: ■ Every module should have a name. Translators provide default names (possibly filenames or null names) for T-modules if neither the source code nor the user specifies otherwise. ■ Every T-module in a collection of linked modules should have a different name so that symbolic debugging systems can distinguish the various line numbers and local symbols. The Microsoft linker does not require or enforce this restriction. Frame A frame is a contiguous region of 64K of memory address space (MAS), beginning on a paragraph boundary (i.e., on a multiple of 16 bytes) or on a selector on the 80286 processor. This concept is useful because the contents of the four 8086 segment registers define four (possibly overlapping) frames; no 16-bit address in the 8086 code can access a memory location outside the current four frames. LSEG (Logical Segment) A logical segment (LSEG) is a contiguous region of memory whose contents are determined at translation time (except for address-binding). Neither the size nor the location in MAS are necessarily determined during translation: the size, although partially fixed, may not be final because the linker may combine the LSEG when linking with other LSEGs, forming a single LSEG. So that it can fit in a frame, an LSEG must not be larger than 64K. Thus, a 16-bit offset, from the base of a frame that covers the LSEG, may address any byte in that LSEG. PSEG (Physical Segment) This term is equivalent to frame. Some prefer "PSEG" to "frame" because the terms PSEG and LSEG reflect the "physical" and "logical" nature of the underlying segments. Frame Number Every frame begins on a paragraph boundary. The "paragraphs" in MAS can be numbered from 0 through 65,535. These numbers, each of which defines a frame, are called frame numbers. Group A group is a collection of LSEGs defined at translation time, whose final locations in MAS have been constrained so that at least one frame exists that covers (contains) every LSEG in the collection. The notation "Gr A(X,Y,Z,)" means that LSEGs X, Y, and Z form a group named A. That X, Y, and Z are all LSEGs in the same group does not imply any ordering of X, Y, and Z in MAS, nor does it imply any contiguity between X, Y, and Z. The Microsoft linker does not currently allow an LSEG to be a member of more than one group. Canonic On the 8086 processor, any location in MAS is contained in exactly 4096 distinct frames, but one of these frames can be distinguished because it has a higher frame number. This frame is called the canonic frame of the location. In other words, the canonic frame of a given byte is the frame chosen so that the byte's offset from that frame lies in the range 0 to 15 (decimal). For example, suppose FOO is a symbol defining a memory location. You would then refer to this frame as the "canonic frame of FOO." Similarly, if S is any set of memory locations, then a unique frame exists that has the lowest frame number in the set of canonic frames of the locations in S. This unique frame is called the canonic frame of the set S. You might refer similarly to the canonic frame of an LSEG or of a group of LSEGs. Segment Name LSEGs are assigned segment names at translation time. These names serve two purposes: ■ During linking, they play a role in determining which LSEGs are combined with other LSEGs. ■ They are used in assembly source code to specify membership in groups. Class Name The translator may optionally assign class names to LSEGs during translation. Classes define a partition on LSEGs: two LSEGs are in the same class if they have the same class name. The Microsoft linker applies the following semantics to class names: the class name "CODE", or any class name whose suffix is "CODE", implies that all segments of that class contain only code and may be considered read-only. Such segments may be overlaid if you specify the module containing the segment as part of an overlay. Overlay Name The linker may optionally assign an overlay name to LSEGs. The overlay name of an LSEG is ignored by Microsoft language linkers for version 3.0 and later languages, but the standard MS-DOS linker supports it. Complete Name The complete name of an LSEG consists of the segment name, class name, and overlay name. The linker combines LSEGs from different modules if their complete names are identical. 7.2 Module Identification and Attributes A module header record, which provides a module name, is always the first record in a module. In addition to having a name, a module may represent a main program and may have a specified starting address. When linking multiple modules together, you should give only one module which has the main attribute. If more than one main module appears, the first takes precedence. In summary, modules may or may not be main and may or may not have a starting address. 7.2.1 Segment Definition A module is a collection of object code defined by a sequence of records that a translator produces. The object code represents contiguous regions of memory whose contents the linker determines during translation. These regions are LSEGs. A module defines the attributes of each LSEG. The segment definition record (SEGDEF) is responsible for maintaining all LSEG information (name, length, memory alignment, etc.). The linker requires the LSEG information when you combine multiple LSEGs and when it establishes segment addressability. The SEGDEF records must follow the first header record. 7.2.2 Addressing a Segment The 8086 addressing mechanism provides segment base registers from which you may address a 64-kilobyte region of memory (a frame). There is one code segment base register (CS), two data segment base registers (DS, ES), and one stack segment base register (SS). The possible number of LSEGs that may make up a memory image far exceeds the number of available base registers. Thus, base registers may require frequent loading. This would be the case in a modular program with many small data and/or code LSEGs. Since such frequent loading of base registers is undesirable, it is a good strategy to collect many small LSEGs together into a single unit that will fit in one memory frame. Then all the LSEGs may be addressed using the same base register value. This addressable unit is a group (see the definition of a group in Section 7.1.1, "Definition of Terms"). To establish addressability of objects within a group, you must explicitly define each group in the module. The group definition record (GRPDEF) lists constituent segments by their segment names. The GRPDEF records within a module must follow all SEGDEF records because GRPDEF records will reference SEGDEF records in defining a group. The GRPDEF records must also precede all other records except header records, which the linker must process first. 7.2.3 Symbol Definition The Microsoft linker supports three different types of records belonging to the class of symbol definition records. The types are public names definition records (PUBDEFs), communal names definition records (COMDEFs), and external names definition records (EXTDEFs). You use these record types to define globally visible procedures and data items and to resolve external references. 7.2.4 Indices "Index" fields appear throughout this chapter. An index is an integer that selects a particular item from a collection of items; for example: name index, segment index, group index, external index, type index, etc. ────────────────────────────────────────────────────────────────────────── Note An index is normally a positive number. The index value zero is reserved, and may carry a special meaning depending on the type of index (for example, a segment index of zero specifies the "Unnamed" absolute pseudo-segment; a type index of zero specifies the "Untyped type"). ────────────────────────────────────────────────────────────────────────── In general, indices must assume values that are quite large (that is, much larger than 255). Nevertheless, a great number of object files contain no indices with values greater than 50 or 100. Therefore, indices are encoded in one or two bytes, as required. The high-order (left-most) bit of the first (and possibly the only) byte determines whether the index occupies one byte or two. If the bit is 0, the index is a number between 0 and 127, occupying one byte. If the bit is 1, the index is a number between 0 and 32K-1, occupying two bytes, and is determined as follows: the low-order eight bits are in the second byte, and the high-order seven bits are in the first byte. 7.3 Conceptual Framework for Fixups A fixup is a modification to object code that achieves address binding that a translator requested and a linker performed. ────────────────────────────────────────────────────────────────────────── Note This is the linker's definition of fixup. Nevertheless, the linker can modify object code (make a "fixup") that does not conform to this definition. For example, binding code to either hardware or software floating-point subroutines is a modification to an operation code, which is treated as an address. The previous definition of fixup is not intended to disallow or discourage modifications to the object code. ────────────────────────────────────────────────────────────────────────── 8086-family translators need four kinds of data to specify a fixup: ■ The place and type of a location to be fixed up. ■ One of two possible fixup modes. ■ A target, which is the memory address to which the location must refer. ■ A frame that defines a context in which the reference takes place. Location ── There are five types of locations: a pointer, a base, an offset, a hibyte, and a lobyte. The vertical alignment of Figure 7.1 illustrates four points (remember that the high-order byte of a word in 8086 memory is the byte with the higher address): ■ A base is the high-order word of a pointer (the linker doesn't care whether the low-order word of the pointer is present). ■ An offset is the low-order word of a pointer (the linker doesn't care whether the high-order word follows). ■ A hibyte is the high-order half of an offset (the linker doesn't care whether the low-order half precedes). ■ A lobyte is the low-order half of an offset (the linker doesn't care whether the high-order half follows). ┌───────────────────┐ Pointer: │ │ └───────────────────┘ ┌─────────┐ Base: │ │ └─────────┘ ┌─────────┐ Offset: │ │ └─────────┘ ┌────┐ Hibyte: │ │ └────┘ ┌────┐ Lobyte: │ │ └────┘ Figure 7.1 Location Types A Location is specified by two kinds of data: the location type, and where it is located. The location type is specified by the LOC field in the FIXUPP record's LOCAT field; where it is located is specified by the Data Record Offset field in the same LOCAT field. Mode ── The Microsoft linker supports two kinds of fixups: self-relative and segment-relative. Self-relative fixups support the 8-bit and 16-bit offsets used in CALL, JUMP, and SHORT-JUMP instructions. Segment-relative fixups support all other addressing modes of the 8086. Target ── The target is the location in MAS that the linker references. (More explicitly, the linker considers the target the lowest byte in the object that it is referencing.) The linker specifies a target by one of five methods. There are three "primary" methods and three "secondary" ones. Each primary method of specifying a target uses two kinds of data: an index number X, and a displacement D. Method Explanation ────────────────────────────────────────────────────────────────────────── (T0) X is a segment index. The target is the Dth byte in the LSEG that the segment index identifies. (T1) X is a group index. The target is the Dth byte in the LSEG that the group index identifies. (T2) X is an external index. The external index identifies the external name that (eventually) gives the address of a byte. The Dth byte following this byte is the ────────────────────────────────────────────────────────────────────────── Each secondary method of specifying a target uses only one item of data ── the index number X; this assumes an implicit displacement equal to zero. Method Explanation ────────────────────────────────────────────────────────────────────────── (T4) X is a segment index. The target is the 0th (first) byte in the LSEG that the segment index identifies. (T5) X is a group index. The target is the 0th (first) byte in the LSEG in the specified group located (eventually) lowest in MAS. (T6) X is an external index. The target is the byte whose address is the external name that the external index ────────────────────────────────────────────────────────────────────────── The following nomenclature describes a target: Nomenclature Method ────────────────────────────────────────────────────────────────────────── Target: SI(segment name), displacement [T0] Target: GI(group name), displacement [T1] Target: EI(symbol name), displacement [T2] Target: SI (segment name) [T4] Target: GI (group name) [T5] Target: EI (symbol name) [T6] ────────────────────────────────────────────────────────────────────────── The following examples illustrate how this notation is used: Sample Nomenclature Explanation ────────────────────────────────────────────────────────────────────────── Target: SI(CODE), 1024 The 1025th byte in the segment CODE. Target: GI(DATAAREA) The location in MAS of a group called DATAAREA. Target: EI(SIN) The address of the external subroutine SIN. Target: EI(PAYSCHEDULE), 24 The 24th byte following the location of an external data structure called ────────────────────────────────────────────────────────────────────────── Frame ── Every 8086 memory reference is to a location contained within a frame. This frame is designated by the contents of a segment register. For the linker to form a correct, usable memory reference, it must know what the target is, and to which frame the reference is being made. Thus, every fixup specifies such a frame, in one of five methods. Some methods use data, X, which is in the index number. Other methods require no data. The five methods of specifying frames are as follows: Method Explanation ────────────────────────────────────────────────────────────────────────── (F0) X is a segment index. The frame is the canonic frame of the LSEG that the segment index defines. (F1) X is a group index. The frame is the canonic frame defined by the group (that is, the canonic frame defined by the LSEG in the group located (eventually) lowest in MAS). (F2) X is an external index. The frame is determined when the linker finds the external name's public definition. There are two cases: Case Explanation ────────────────────────────────────────────────────────────────────────── (F2a) The linker defines the symbol relative to some LSEG, and there is no associated group. The linker also specifies the LSEG's canonic frame. (F2c) Regardless of how the linker defines the symbol, there is an associated group. And the linker specifies the canonic frame of the group. (The Group Index field of the PUBDEF ────────────────────────────────────────────────────────────────────────── Method Explanation ────────────────────────────────────────────────────────────────────────── (F4) No X. The frame is the canonic frame of the LSEG that contains the location. (F5) No X. The target determines the frame. There are three ────────────────────────────────────────────────────────────────────────── Case Explanation ────────────────────────────────────────────────────────────────────────── (F5a) The target specifies a segment index: in this case, the frame is determined as in (F0). (F5b) The target specifies a group index: in this case, the frame is determined as in (F1). (F5c) The target specifies an external index: in this case, the frame is ────────────────────────────────────────────────────────────────────────── The nomenclature that describes frames is similar to the above nomenclature for targets. Nomenclature Method ────────────────────────────────────────────────────────────────────────── Frame: SI (segment name) [F0] Frame: GI (group name) [F1] Frame: EI (symbol name) [F2] Frame: Location [F4] Frame: target [F5] Frame: None [F6] ────────────────────────────────────────────────────────────────────────── For an 8086 memory reference, the frame specified by a self-relative reference is usually the canonic frame of the LSEG that contains the location. Also, the frame specified by a segment-relative reference is the canonic frame of the LSEG that contains the target. 7.3.1 Self-Relative Fixup A self-relative fixup works as follows: the location implicitly defines a memory address──namely, the address of the byte following the location (because at the time of a self-relative reference, the 8086 IP (Instruction Pointer) is pointing to the byte following the reference). For 8086 self-relative references, if either the location or the target is outside the specified frame, the linker gives a warning. Otherwise, there is a unique l6-bit displacement that, when added to the address implicitly defined by the location, yields the relative position of the target in the frame. ■ If the location is an offset, the linker adds the displacement to the location (modulo 65,536) and reports no errors. ■ If the location is a lobyte, the displacement must be within the range {-128:127}; otherwise, the linker gives a warning. The linker adds the displacement to the location (modulo 256). ■ If the location is a base, pointer, or hibyte, it is unclear what the translator intended, so the linker's action is undefined. 7.3.2 Segment-Relative Fixup A segment-relative fixup operates as follows: a nonnegative 16-bit number, FBVAL, is defined as the frame number of the frame or selector value that the fixup specifies. A signed 20-bit number, FOVAL, is defined as the distance from the base of the frame to the target. If this signed 20-bit number is less than 0 or greater than 65,535, the linker reports an error. Otherwise, the linker uses FBVAL and FOVAL to fix up the location in the following fashion: ■ If the location is a pointer, the linker adds FBVAL (modulo 65,536) to the high-order word of the pointer, and adds FOVAL (modulo 65,536) to the low-order word of the pointer. ■ If the location is a base, the linker adds FBVAL (modulo 65,536) to the base and ignores FOVAL. ■ If the location is an offset, the linker adds FOVAL (modulo 65,536) to the offset and ignores FBVAL. ■ If the location is a hibyte, the linker adds (FOVAL/256) (modulo 256) to the hibyte and ignores FBVAL. (The division indicated is integer division; that is, the linker discards the remainder.) ■ If the location is a lobyte, the linker adds (FOVAL modulo 256) (modulo 256) to the lobyte and ignores FBVAL. 7.4 Record Sequence An object code file must contain a sequence of one or more modules, or a library containing zero or more modules. The following syntax shows the valid record ordering necessary to form a module. In addition, the given semantic rules provide information about how to interpret the record sequence. ────────────────────────────────────────────────────────────────────────── Note The description language used in the following syntax is defined in WIRTH: CACM, November 1977, vol. 20, no. 11, pp. 822-823. The character strings represented by capital letters are not literals but identifiers, and are further defined in the record format section. ────────────────────────────────────────────────────────────────────────── object file = tmodule tmodule = {THEADR | LHEADR} seg-grp {component} modtail seg_grp = {LNAMES} {SEGDEF} {EXTDEF | GRPDEF} component = data | debug_record data = content_def | thread_def | PUBDEF | EXTDEF | COMDEF | LOCSYM debug_record = LINNUM content_def = data_record {FIXUPP} thread_def = FIXUPP (containing only Thread fields) data_record = LIDATA | LEDATA modtail = MODEND The following rules apply: ■ A FIXUPP record always refers to the previous data record. ■ All LNAMES, SEGDEF, GRPDEF, and EXTDEF records must precede all records that refer to them. ■ Comment records may appear anywhere in a file, except as the first or last record in a file or module, or within a content_def. 7.5 Introducing the Record Formats The following pages present diagrams of record formats in schematic form. Here is a sample record format that illustrates the various conventions: 7.5.1 Sample Record Format (SAMREC) ┌─────┬──────────┬─────///────┬────||||────┬─────┐ │ │ │ │ │ │ │ REC │ Record │ Name │ Number │ CHK │ │ TYP │ Length │ │ │ SUM │ │ xxH │ │ │ │ │ │ │ │ │ │ │ └─────┴──────────┼────///─────┼────||||────┴─────┘ │ │ └────rpt─────┘ The Title and Official Abbreviation At the top of the figure is the name of the record format described, with its official abbreviation. To promote uniformity among various programs, including translators and debuggers, use the abbreviation in both code and documentation. The abbreviation of the record format is always six letters. The Boxes Each format is drawn with boxes of two sizes. A narrow box represents a single byte. A plain wide box represents two bytes. The wide boxes with three slashes in the top and bottom represent a variable number of bytes, one or more, depending upon the content. The wide boxes with four vertical bars in the top and bottom represent four-byte fields. RECTYP The first byte in each record contains a value between 0 and 255, indicating the record type. Record Length The second field in each record contains the number of bytes in the record, exclusive of the first two fields, where a field is a 16-bit number──a low byte followed by a high byte. Name Any field that indicates a name has the following internal structure: the first byte contains a number between 0 and 127, inclusive, indicating the number of remaining bytes in the field. The remaining bytes are interpreted as a byte string. Most translators constrain the character set to a subset of the ASCII character set. Number A four-byte number field represents a 32-bit unsigned integer, where the first eight bits (least-significant) are stored in the first byte (lowest address), the next eight bits are stored in the second byte, and so on. Repeated or Conditional Fields Some portions of a record format contain a field or series of fields that may be repeated one or more times. Such portions are indicated by the "repeated" or "rpt" brackets below the boxes. Similarly, some portions of a record format are present only if some given condition is true; these fields are indicated by similar "conditional" or "cond" brackets below the boxes. CHKSUM The last field in each record is a check sum, which contains the two's complement of the sum (modulo 256) of all other bytes in the record. Therefore, the sum (modulo 256) of all bytes in the record is zero. Bit Fields Sometimes descriptions of the contents of fields are at the bit level. Boxes with vertical lines drawn through them represent bytes or words; the vertical lines indicate bit boundaries. Thus, the following byte representation has three bit fields of three, one, and four bits, respectively. ┌───────────┬───┬───────────────┐ │ │ │ │ │ │ │ │ │ │ │ │ └───────────┴───┴───────────────┘ 3 1 4 7.5.2 T-Module Header Record (THEADR) ┌─────┬──────────┬─────///────┬─────┐ │ │ │ │ │ │ REC │ Record │ T- │ CHK │ │ TYP │ Length │ Module │ SUM │ │ 80H │ │ Name │ │ │ │ │ │ │ └─────┴──────────┴────///─────┴─────┘ T-Module Name The T-Module Name field contains the name for the T-module. 7.5.3 L-Module Header Record (LHEADR) ┌─────┬──────────┬─────///────┬─────┐ │ │ │ │ │ │ REC │ Record │ L- │ CHK │ │ TYP │ Length │ Module │ SUM │ │ 82H │ │ Name │ │ │ │ │ │ │ └─────┴──────────┴────///─────┴─────┘ L-Module Name The L-Module Name field contains the name for the L-module. Every module output from a translator must have a T-module or L-module header record. The linker requires a THEADR or LHEADR record to come first in the module and ignores any others. The LHEADR record is identical to the THEADR record, except it has a record type of 82H. 7.5.4 List of Names Record (LNAMES) ┌─────┬──────────┬─────///────┬─────┐ │ │ │ │ │ │ REC │ Record │ Name │ CHK │ │ TYP │ Length │ │ SUM │ │ 96H │ │ │ │ │ │ │ │ │ └─────┴──────────┼────///─────┼─────┘ │ │ └────rpt─────┘ The LNAMES record contains a list of names that the following SEGDEF and GRPDEF records may use as the names of segments, classes, and/or groups. The order of LNAMES records in a module and the order of names within each LNAMES record imply a mapping of these names to numbers: 1, 2, 3, etc. These numbers are used as "Name Indices" in the Segment Name Index, Class Name Index, and Group Name Index fields of the SEGDEF and GRPDEF records. Name This repeatable field provides a name, which may have zero length. 7.5.5 Segment Definition Record (SEGDEF) ┌───┬────────┬───///───┬─────────┬───///───┬─///─┬─///─┬───┐ │ │ │ │ │ │ │ │ │ │REC│ Record │ Segment │ Segment │ Segment │Class│Over │CHK│ │TYP│ Length │ ATTR │ Length │ Name │Name │Lay │SUM│ │98H│ │ │ │ Index │Index│Name │ │ │ │ │ │ │ │ │Index│ │ └───┴────────┴───///───┴─────────┴───///───┴─///─┴─///─┴───┘ Segment index values 1 through 32,767, which are used in other record types to refer to specific LSEGs, are defined implicitly by the sequence in which SEGDEF records appear in the object file. Segment ATTR The Segment ATTR field provides information on various attributes of a segment, and has the following format: ┌─────┬────────┬───────┐ │ │ │ │ │ ACB │ Frame │ Off- │ │ P │ Number │ Set │ │ │ │ │ │ │ │ │ └─────┼────────┴───────┤ │ │ └───conditional──┘ The ACBP byte contains four numbers──the A, C, B, and P attribute specifications. This byte has the following format: ┌───────────┬───────────┬───┬───┐ │ │ │ │ │ │ A │ C │ B │ P │ │ │ │ │ │ └───────────┴───────────┴───┴───┘ A (Alignment) is a 3-bit subfield that specifies the alignment attribute of the LSEG. The semantics are defined as follows: Attribute Explanation ────────────────────────────────────────────────────────────────────────── A=0 SEGDEF describes an absolute LSEG. A=1 SEGDEF describes a relocatable, byte-aligned LSEG. A=2 SEGDEF describes a relocatable, word-aligned LSEG. A=3 SEGDEF describes a relocatable, paragraph-aligned LSEG. A=4 SEGDEF describes a relocatable, page(256-byte)-aligned LSEG. ────────────────────────────────────────────────────────────────────────── If A=0, the Frame Number and Offset fields are present. With the Microsoft linker, you may use absolute segments for addressing only; for example, to define the starting address of a ROM and to define symbolic names for addresses within the ROM. The linker ignores any data that belongs to an absolute LSEG and issues a warning if absolute segments are defined for a program that runs in protected mode. C (Combination) is a 3-bit subfield that specifies the combination attribute of the LSEG. Absolute segments (A=0) must have combination zero (C=0). For relocatable segments, the C field encodes a number (0,1,2,3,4,5,6, or 7) that indicates how the segment can be combined. One way to interpret this attribute is to consider how two LSEGs are combined. For example, suppose that X and Y are LSEGs, and that Z is the LSEG resulting from the combination of X and Y. Let LX and LY be the lengths of X and Y, and let MXY denote the maximum of LX, LY. Now, to accommodate the alignment attribute of Y, let G be the length of any gap required between the X and Y components of Z. Then, let LZ denote the length of the (combined) LSEG, Z; let dx (0(<=dx<LX) be the offset in X of a byte and, similarly, let dy be the offset (of a byte) in Y. The following table gives the length LZ of the combined LSEG, Z, and the offsets dx' and dy' in Z for the bytes corresponding to dx in X and to dy in Y. Table 7.2 Combination Attribute Example C LZ dx' dy' ────────────────────────────────────────────────────────────────────────── 2 LX+LY+G dx dy+LX+G "Public" 5 LX+LY+G dx dy+LX+G "Stack" 6 MXY dx dy "Common" ────────────────────────────────────────────────────────────────────────── Table 7.2 has no lines for C=0, 1, 3, 4, or 7. C=0 indicates that the relocatable LSEG may not be combined. C=1 and C=3 are undefined. C=4 and C=7 are treated the same as C=2. B (Big) is a 1-bit subfield that, if set to 1, indicates that the segment length is exactly 64K (65,536 bytes). In this case, the Segment Length field must contain zero. The P field must always be zero. The Frame Number and Offset fields (present only for absolute segments, A=0) specify the placement in MAS of the absolute segment. Offset is in the range between 0 and 15, inclusive. If you want an offset value larger than 15, you should adjust the frame number. Segment Length The Segment Length field gives a segment's length in bytes. This length may be zero. If it is, the linker does not delete the segment from the module. The Segment Length field is only large enough to hold numbers from 0 to 64K-1, inclusive. To give the segment a length of 64K, you must use the B attribute bit in the ACBP field (see Segment ATTR in this section). Segment Name Index The segment name is a name that a programmer or translator assigns to the segment; for example, CODE, DATA, MODULENAME_CODE, TAXDATA, or STACK. The Segment Name Index field provides the segment name by indexing into the list of names provided by the LNAMES record. Class Name Index The class name is a name that a programmer or translator assigns to a segment. If none is assigned, the name is null and has a length of zero. The purpose of a class name is to let the programmer define a "handle" to order the LSEGs in MAS; for example, RED, WHITE, BLUE; or ROM, FASTRAM, DISPLAYRAM. The Class Name Index field provides the class name by indexing into the list of names provided by the LNAMES record. Overlay Name Index The overlay name is a name that the translator and/or the linker, at the programmer's request, applies to a segment. The overlay name, like the class name, may be null. The Overlay Name Index field provides the overlay name by indexing into the list of names provided by the LNAMES record. ────────────────────────────────────────────────────────────────────────── Note Microsoft language linkers (versions 3.00 and later) ignore the Overlay Name Index field, but the standard MS-DOS linker supports it. ────────────────────────────────────────────────────────────────────────── 7.5.6 Group Definition Record (GRPDEF) ┌─────┬──────────┬─────///────┬────///─────┬─────┐ │ │ │ │ │ │ │ REC │ Record │ Group │ Group │ CHK │ │ TYP │ Length │ Name │ Component │ SUM │ │ 9AH │ │ Index │ Descriptor │ │ │ │ │ │ │ │ └─────┴──────────┴──///───────┤──///───────┼─────┘ │ │ └──repeated──┘ Group Name Index The linker may reference a collection of LSEGs with the group name. Most importantly, when the LSEGs are eventually fixed in MAS, a frame must exist that "covers" every LSEG of the group. The Group Name Index field provides the group name by indexing into the list of names provided by the LNAMES record. Group Component Descriptor This repeatable field has the following format: ┌─────┬────///────┐ │ │ │ │ FFH │ Segment │ │ │ Index │ │ │ │ │ │ │ └─────┴────///────┘ The first byte of the Group Component Descriptor field contains 0FFH; the descriptor contains one field, which is a segment index that selects the LSEG described by a preceding SEGDEF record. 7.5.7 Public Names Definition Record (PUBDEF) ┌────┬──────────┬────///──┬───///───┬───────┬──///──┬─────┐ │ │ │ │ │ │ │ │ │ REC│ Record │ Public │ Public │Public │ Type │ CHK │ │ TYP│ Length │ Base │ Name │Offset │ Index │ SUM │ │ 90H│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └────┴──────────┴────///──┼──///────┴───────┴─///───┼─────┘ │ │ └─────────repeated────────┘ The PUBDEF record provides a list of one or more public names. For each name, three kinds of data are provided: (1) a base value for the name, (2) the offset value of the name, and (3) the type of entity represented by the name. Public Base The Public Base field has the following format: ┌────///────┬────///────┬───────────┐ │ │ │ │ │ Group │ Segment │ Frame │ │ Index │ Index │ Number │ │ │ │ │ └────///────┴────///────┼───────────┤ │ │ └conditional┘ The Group Index field has a format, which was given earlier, and contains a number between 0 and 32,767, inclusive. A nonzero value in the Group Index field associates a group with the public symbol and is used as described in case (F2c) of Section 7.3, "Conceptual Framework for Fixups." A zero value in the Group Index field indicates that there is no associated group. The Segment Index field has a format, which was given earlier, and contains a number between 0 and 32,767, inclusive. A nonzero value in the Segment Index field selects an LSEG. In this case, the location of each public symbol defined in the record is taken as a nonnegative displacement (given by a Public Offset field) from the first byte of the selected LSEG. Also, the Frame Number field must be absent. A zero value in the Segment Index field means that the defined symbols are absolute, and that the absolute addresses of the symbols are the values in the Public Offset field. The Group Index field is ignored. The Frame Number field contains a frame number only if the value of the Segment Index field is zero. The linker ignores this field. A nonzero value in the Group Index field selects some group. This group is taken as the "frame of reference" for references to all public symbols defined in this record. That is, the linker performs the following actions: ■ The linker converts any fixup of the form: Target: EI(P) Frame: Target (where P is a public symbol in this PUBDEF record) to a fixup of the form: Target: SI(L),d Frame: GI(G) where SI(L) and d are provided by the Segment Index and Public Offset fields. (The "normal" action would have the frame specifier in the new fixup be the same as in the old fixup: Frame:Target.) ■ When the linker converts the value of a public symbol, as defined by the Segment Index, Public Offset, and (optionally) Frame Number fields, to a {base,offset} pair, the base part is the base of the indicated group. A zero value in the Group Index field selects no group. The linker does not alter the frame specification of fixups referencing the symbol, and takes, as the base part of the absolute value of the public symbol, the canonic frame of the segment (either LSEG or PSEG) determined by the Segment Index field. Public Name The Public Name field gives the name of the object whose location in MAS is made available to other modules by the linker. The name must contain one or more characters. Public Offset The Public Offset field is a 16-bit value. It is either the offset of the public symbol with respect to an LSEG (if the segment index is greater than zero), or the offset of the public symbol with respect to the specified frame (if the segment index is equal to zero). Type Index The Type Index field identifies a single preceding TYPDEF (Type Definition Record), which contains a descriptor for the type of entity represented by the public symbol. The linker ignores this field. 7.5.8 Communal Names Definition Record (COMDEF) ┌─────┬─────┬────///────┬────///────┬──────┬──────────┬─────┐ │ │ │ │ │ │ │ │ │ REC │ REC │ Communal │ Type │ Data │ Communal │ CHK │ │ TYP │ LEN │ Name │ Index │ Seg │ Length │ SUM │ │ B0H │ │ │ │ Type │ │ │ │ │ │ │ │ │ │ │ └─────┴─────┼────///────┴────///────┴──────┴──────────┼─────┴ │ │ └───────repeated──────────────────────────┘ The COMDEF record provides a list of one or more Communal Names, which define communal variables. A communal variable is an uninitialized public variable whose final size and location are not fixed during compiling. Communal variables are similar to FORTRAN common blocks in that if you are linking object modules that each declare a communal variable, then the size of that variable is the largest of the declared variables. In the C language, all uninitialized public variables are communal. The following example shows three different declarations of the same C communal variable: char foo[4]; /* In file a.c */ char foo[1]; /* In file b.c */ char foo[1024]; /* In file c.c */ If the objects produced from a.c, b.c, and c.c are linked together, the linker allocates 1024 bytes for the character array "foo." ────────────────────────────────────────────────────────────────────────── Note This record requires that a COMENT record from the Microsoft Extensions class appear before it in the object module. ────────────────────────────────────────────────────────────────────────── Communal Name The Communal Name field gives the communal variable name and must contain one or more characters. Communal names are treated as external names when an external name is requested elsewhere in the module. Communal names are ordered together with external names for the purpose of referring to an external name by its index. (See the description of the EXTDEF record later in this section for more details on external names.) Type Index The Type Index field is ignored by the Microsoft linker. Data Segment Type The Data Segment Type field is a single byte that describes the data segment in which the communal variable resides. It can contain the following values: 62H (NEAR) = the communal variable is in the default data segment. 61H (FAR) = the communal variable is not in the default data segment. Communal Length The Communal Length field describes the length of the communal variable according to its data segment type. If its value is NEAR (62H), the field represents the length in bytes. If its value is FAR (61H), the field represents: ┌─────//────┬─────///──────┐ │ Number of │ Element size │ │ elements │ in bytes │ └────///────┴─────///──────┘ The format of all the length fields is as follows: ┌─────┐ │ │ │ 0 │ │ to │ │ 127 │ │ │ └─────┘ ┌─────┬───────────┐ │ │ │ │ │ 0 │ │ 129 │ to │ │(81H)│ 64K-1 │ │ │ │ └─────┴───────────┘ ┌─────┬─────────────────┐ │ │ │ │ │ 0 │ │ 132 │ to │ │(84H)│ 16M-1 │ │ │ │ └─────┴─────────────────┘ ┌─────┬─────────────────┐ │ │ │ │ │ -2G-1 │ │ 136 │ to │ │(88H)│ 2G-1 │ │ │ │ └─────┴─────────────────┘ The first format (single byte), containing a value between 0 and 127, represents the number given. The second format, with a leading byte containing 129, represents the number contained in the following two bytes. The third format, with a leading byte containing 132, represents the number contained in the following three bytes. The fourth format, with a leading byte containing 136, represents the number contained in the following four bytes with its sign extended if necessary. Link-Time Semantics A PUBDEF matching a communal variable definition overrides the communal variable definition. Two communal variable definitions match if the names in their definitions match. If two matching definitions disagree on whether a communal variable is NEAR or FAR, the linker assumes the variable is NEAR. If the variable is NEAR, then its size is the largest of the sizes specified for it. If the variable is FAR, the linker issues a warning if the array element sizes conflict. If these sizes don't conflict, the variable's size is the element size multiplied by the largest number of elements specified. In addition, the sum of the sizes of all NEAR variables must not exceed 64 kilobytes, and the sum of the sizes of all FAR variables must not exceed the size of the machine's addressable memory space. HUGE Communal Variables: A FAR communal variable that is larger than 64 kilobytes (a HUGE communal variable) resides in segments that are contiguous (on an 8086) or that have consecutive selectors (on an 80286). No other data items reside in the segments occupied by a HUGE communal variable. If the linker finds matching HUGE and NEAR communal variable definitions, it issues a warning message, since it is impossible for a NEAR variable to be larger than 64 kilobytes. 7.5.9 Local Symbols Record (LOCSYM) ┌────┬──────────┬────///──┬───///───┬───────┬──///──┬─────┐ │ │ │ │ │ │ │ │ │ REC│ Record │ Local │ Local │ Local │ Type │ CHK │ │ TYP│ Length │ Base │ Name │Offset │ Index │ SUM │ │ 92H│ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └────┴──────────┴────///──┼──///────┴───────┴─///───┼─────┘ │ │ └─────────repeated────────┘ The LOCSYM record provides information for the definition of a local symbol, one that is visible only within the module in which it is defined. The form and meaning of each of the fields is identical to those in the PUBDEF record. ────────────────────────────────────────────────────────────────────────── Note The LOCSYM record requires that a COMENT record from the Microsoft Extensions class appear before it in the object module. Also, it is only recognized by Microsoft language linkers later than version 3.07. ────────────────────────────────────────────────────────────────────────── 7.5.10 External Names Definition Record (EXTDEF) ┌─────┬───────────┬────///────┬────///────┬─────┐ │ │ │ │ │ │ │ REC │ Record │ External │ Type │ CHK │ │ TYP │ Length │ Name │ Index │ SUM │ │ 8CH │ │ │ │ │ │ │ │ │ │ │ └─────┴───────────┼────///────┴────///────┼─────┘ │ │ └───────repeated────────┘ The EXTDEF record provides a list of external names and, for each name, the type of object it represents. The linker assigns to each external name the value provided by an identical public name or local name (if such a name is found). External Name The External Name field provides the external object name, which must have a nonzero length. Including a name in an EXTDEF record is an implicit request to link the object file to a module containing the same name declared as a public symbol, unless the name is defined as a local symbol within the same module as the EXTDEF. This request determines whether or not the external name is referenced within some FIXUPP record in the module. The order of EXTDEF records in a module and the order of external names within each EXTDEF record, together with COMDEF records and communal names, imply a mapping on the set of all external names requested by the module; for example: 1, 2, 3, etc. So to refer to a particular external name, the linker uses these numbers as "external indices" in the Target Datum and/or Frame Datum fields of FIXUPP records. External indices may not reference forward. For example, an EXTDEF defining the kth object must precede any record referring to that object with index k. Type Index The Type Index field is ignored by the Microsoft linker, except for linker versions earlier than 3.05, and for object modules lacking the COMENT record from the Microsoft Extensions class. For that case, refer to Section 7.6, "Microsoft Type Representations for Communal Variables." 7.5.11 Line Numbers Record (LINNUM) ┌─────┬──────────┬─────///───┬───────────┬───────────┬─────┐ │ │ │ │ │ │ │ │ REC │ Record │ Line │ Line │ Line │ CHK │ │ TYP │ Length │ Number │ Number │ Number │ SUM │ │ 94H │ │ Base │ │ Offset │ │ │ │ │ │ │ │ │ └─────┴──────────┴────///────┼───────────┴───────────┼─────┘ │ │ └────────repeated───────┘ The LINNUM record allows a translator to relate a line number in source code to the corresponding line in translated code. Line Number Base The Line Number Base field has the following format: ┌────///────┬────///────┐ │ │ │ │ Group │ Segment │ │ Index │ Index │ │ │ │ └────///────┴────///────┘ The Group Index field is ignored by the Microsoft linker. The Segment Index field determines the location of the first byte of code corresponding to some source line number. Line Number The Line Number field provides a binary line number between 0 and 32,767, inclusive. If the high-order bit is not zero, the number is considered undefined. Line Number Offset The Line Number Offset field is a 16-bit value, which is the offset of the line number with respect to an LSEG (if the segment index is greater than zero). 7.5.12 Logical Enumerated Data Record (LEDATA) ┌─────┬───────────┬────///────┬───────────┬─────┬─────┐ │ │ │ │ │ │ │ │ REC │ Record │ Segment │ Enumerated│ │ CHK │ │ TYP │ Length │ Index │ Data │ DAT │ SUM │ │ A0H │ │ │ offset │ │ │ │ │ │ │ │ │ │ └─────┴───────────┴────///────┴───────────┼─────┼─────┘ │ │ └─rpt─┘ The LEDATA record provides contiguous data from which the linker may construct a portion of an 8086 memory image. Segment Index The Segment Index field, which must be nonzero, specifies an index relative to the SEGDEF records that precede the LEDATA record. Enumerated Data Offset The Enumerated Data Offset field specifies an offset that is relative to the base of the LSEG specified by the segment index. The field also defines the relative location of the first byte of the DAT field. Successive data bytes in the DAT field occupy successively higher locations of memory. DAT The DAT field provides up to 1024 consecutive bytes of relocatable or absolute data. 7.5.13 Logical Iterated Data Record (LIDATA) ┌─────┬──────────┬────///────┬───────────┬────///────┬─────┐ │ │ │ │ │ │ │ │ REC │ Record │ Segment │ Iterated │ Iterated │ CHK │ │ TYP │ Length │ Index │ Data │ Data │ SUM │ │ A2H │ │ │ Offset │ Block │ │ │ │ │ │ │ │ │ └─────┴──────────┴────///────┴───────────┼────///────┼─────┘ │ │ └─repeated──┘ The LIDATA record provides contiguous data from which the linker may construct a portion of an 8086 memory image. Segment Index The Segment Index field, which must be nonzero, specifies an index that is relative to the SEGDEF records that precede the LIDATA record. Iterated Data Offset The Iterated Data Offset field specifies an offset that is relative to the base of the LSEG specified by the segment index. It also defines the relative location of the first byte in the iterated data block. Successive data bytes in the iterated data block occupy successively higher locations of memory. Iterated Data Block This repeated field is a structure specifying the repeated data bytes. It has the following format: ┌──────────┬────────────┬────///────┐ │ │ │ │ │ Repeat │ Block │ │ │ Count │ Count │ Content │ │ │ │ │ │ │ │ │ └──────────┴────────────┴────///────┘ ────────────────────────────────────────────────────────────────────────── Note The linker cannot handle LIDATA records whose iterated data blocks are larger than 512 bytes. ────────────────────────────────────────────────────────────────────────── Repeat Count: The Repeat Count field specifies the number of times to repeat the Content portion of this iterated data block. The value of the Repeat Count field must be nonzero. Block Count: The Block Count field specifies the number of iterated data blocks in the Content portion of this iterated data block. If the Block Count field has a value of zero, the Content portion of the iterated data block is interpreted as data bytes. If the field is nonzero, the Content portion is interpreted as that number of iterated data blocks. Content: The Content field may be interpreted in one of two ways, depending on the value of the previous Block Count field. If the Block Count field is zero, this field is a 1-byte count followed by the indicated number of data bytes. But if the Block Count field is nonzero, the Content field is interpreted as the first byte of another iterated data block. 7.5.14 Fixup Record (FIXUPP) ┌─────┬───────────┬────///────┬─────┐ │ │ │ │ │ │ REC │ Record │ Thread │ CHK │ │ TYP │ Length │ or │ SUM │ │ 9CH │ │ Fixup │ │ │ │ │ │ │ └─────┴───────────┼────///────┼─────┘ │ │ └────rpt────┘ The FIXUPP record specifies zero or more fixups. Each fixup requests a modification (fixup) to a location within the previous data record. A data record may be followed by more than one FIXUPP record that refers to it. Each fixup is specified by a Fixup field that specifies four kinds of data: a location, a mode, a target, and a frame. The frame and target may be specified completely within the Fixup field, or by reference to a preceding Thread field. A Thread field specifies a default target or frame that subsequently may be referred to. Eight threads are provided──four for frame specification and four for target specification. Once a thread has specified a target or frame, any Fixup fields that follow (in the same or following FIXUPP records) may refer to that target or frame until another Thread field with the same type (target or frame) and thread number (0-3) appears (in the same or in another FIXUPP record). Thread The Thread field has the following format: ┌─────┬────///────┐ │ │ │ │ TRD │ Index │ │ DAT │ │ │ │ │ └─────┼────///────│ │ │ └condiional─┘ The TRD DAT (Thread Data) field is a byte with the following internal structure: ┌───┬───┬───┬───────────┬───────┐ │ │ │ │ │ │ │ 0 │ D │ 0 │ Method │ THRED │ │ │ │ │ │ │ └───┴───┴───┴───────────┴───────┘ The D field is one bit and defines the type of thread being used. If D=0, this bit defines a target thread, and if D=1, it defines a frame thread. Method is a 3-bit field containing a number between 0 and 3 (if D=0) or a number between 0 and 6 (if D=1). If D=0, then Method = (0, 1, 2, 4, 5, 6)mod 4, where 0, 1, 2, 4, 5, 6 indicate methods T0, T1, T2, T4, T5, and T6 of specifying a target. Thus, Method indicates the kind of index or frame number required to specify the target, without indicating whether the target is specified by a primary or secondary method. If D=1, then Method = 0, 1, 2, 4, 5, corresponding to methods F0, F1, F2, F4, F5 of specifying a frame. Here, Method indicates the kind (if any) of index required to specify the frame. The THRED field contains a number between 0 and 3, inclusive, and associates a thread number to the frame or target defined by the Thread field. The Index field contains a segment index, group index, or external index depending on the specification in the Method field. If Method specifies F4 or F5, this field will not be present. Fixup The Fixup field has the following format: ┌───────────┬─────┬────///────┬────///────┬────///────┐ │ │ │ │ │ │ │ LOCAT │ FIX │ Frame │ Target │ Target │ │ │ DAT │ Datum │ Datum │ Dis- │ │ │ │ │ │ Placement │ │ │ │ │ │ │ └───────────┴─────┼────///────┼────///────┼────///────│ │ │ │ │ └────────────conditional────────────┘ The LOCAT field is a byte pair with the following format: ┌───┬───┬───┬───────────┬───────────────────────────────────────┐ │ │ │ │ │ │ │ 1 │ M │ 0 │ LOC │ D a t a R e c o r d O f f s e t │ │ │ │ │ │ │ ├───┴───┴───┴───────────┴───────┬───────────────────────────────┤ │ │ │ └────────────lo byte────────────┴────────────hi byte────────────┘ M is a 1-bit field that specifies the mode of the fixups: self-relative (if M=0) or segment-relative (if M=1). ────────────────────────────────────────────────────────────────────────── Note Self-relative fixups may not be applied to LIDATA records. ────────────────────────────────────────────────────────────────────────── LOC is a 3-bit field indicating that the byte(s) in the preceding data record to be fixed up are a lobyte (if LOC=0), an offset (if LOC=1), a base (if LOC=2), a pointer (if LOC=3), a hibyte (if LOC=4), or a "loader-resolved" offset (if LOC=5). Any other values in LOC are invalid. The Data Record Offset field contains a number between 0 and 1023, inclusive, that gives the relative position of the lowest order byte of location (the actual bytes being fixed up) within the preceding data record. The Data Record Offset value is relative to the first byte in the data fields in the data records. ────────────────────────────────────────────────────────────────────────── Note If the preceding data record is an LIDATA record, it is possible for the Data Record Offset value to designate a location within a Repeat Count field or a Block Count field of the Iterated Data Block field. Such a reference is an error. The linker's action on such a malformed record is undefined. ────────────────────────────────────────────────────────────────────────── The FIX DAT field is a byte with the following format: ┌───┬───────────┬───┬───┬───────┐ │ │ │ │ │ │ │ F │ Frame │ T │ P │ TARGT │ │ │ │ │ │ │ └───┴───────────┴───┴───┴───────┘ F is a 1-bit subfield that specifies whether the frame for this fixup is specified by a thread (if F=1) or explicitly (if F=0). The Frame field contains a number that is interpreted in one of two ways, as indicated by the F bit. If F is zero, the Frame field contains a number between 0 and 5, inclusive, corresponding to methods F0,...,F5 for specifying a frame. If F=1, then the Frame field contains a thread number (0-3). It specifies the frame most recently defined by a Thread field that defined a frame thread with the same thread number. (Notice that the Thread field may appear in the same FIXUPP record, or in an earlier one.) T is a 1-bit field that specifies whether the target specified for this fixup is defined by reference to a thread (T=1), or is given explicitly in the Fixup field (T=0). P is a 1-bit field that indicates whether the Target is specified by a primary method (requires a target displacement, if P=0) or by a secondary method (requires no target displacement, if P=1). Since a target thread does not have a primary/secondary attribute, the P bit is the only field that contains the target specification attribute. TARGT is interpreted as a 2-bit field. When T=0, it provides a number between 0 and 3, inclusive, corresponding to methods T0, T1, T2 or T4, T5, T6, depending on the value of P (where P is interpreted as the high-order bit of T0, T1, T2, T4, T5, or T6). When a thread specifies the target (if T=1), then the TARGET field specifies a thread number (0-3). The Frame Datum field is the "referent" portion of a frame specification, and is a segment index, group index, or external index. The Frame Datum field is present only when the frame is not specified by a thread (if F=0) or explicitly by methods F4, F5, or F6. The Target Datum field is the "referent" portion of a target specification, and is a segment index, group index, or external index. The Target Datum field is present only when a thread does not specify the target (if T=0). The Target Displacement field is the 2-byte displacement required by primary methods of specifying targets. This field is present if P=0. ────────────────────────────────────────────────────────────────────────── Note All these methods are described in Section 7.3, "Conceptual Framework for Fixups." ────────────────────────────────────────────────────────────────────────── 7.5.15 Module End Record (MODEND) ┌─────┬───────────┬─────┬────///────┬─────┐ │ │ │ │ │ │ │ REC │ Record │ MOD │ START │ CHK │ │ TYP │ Length │ TYP │ ADDRS │ SUM │ │ 8AH │ │ │ │ │ │ │ │ │ │ │ └─────┴───────────┴─────┼────///────┼─────┘ │ │ └conditional┘ The MODEND record serves two purposes. It denotes the end of a module and indicates whether or not the module that just ended specifies an entry point to begin execution. If it does not, the linker specifies the execution address. MOD TYP The MOD TYP field specifies the attributes of the module. The bit allocation and associated meanings are as follows: ┌───────┬───┬───┬───┬───┬───┬───┐ │ │ │ │ │ │ │ │ │ MATTR │ 0 │ 0 │ 0 │ 0 │ 0 │ 1 │ │ │ │ │ │ │ │ │ └───────┴───┴───┴───┴───┴───┴───┘ MATTR is a 2-bit field that specifies the following module attributes: MATTR Module Attribute ────────────────────────────────────────────────────────────────────────── 0 Non-main module with no START ADDRS 1 Non-main module with START ADDRS 2 Main module with no START ADDRS 3 Main module with START ADDRS ────────────────────────────────────────────────────────────────────────── The START ADDRS field (present only if MATTR is 1 or 3) has the following format: ┌─────┬────///────┬────///────┬───────────┐ │ │ │ │ │ │ END │ Frame │ Target │ Target │ │ DAT │ Datum │ Datum │ Dis- │ │ │ │ │ Placement │ │ │ │ │ │ └─────┼────///────┴────///────┴───────────│ │ │ └────────────conditional────────────┘ The starting address of a module has all the attributes of any other logical reference found in a module. The mapping of a logical starting address to a physical starting address is done in the same manner as mapping any other logical address to a physical address, as specified in the discussion of fixups and the FIXUPP record. The fields of the START ADDRS field have the same semantics as the FIX DAT, Frame Datum, Target Datum, and Target Displacement fields in the FIXUPP record. Only primary fixup methods are allowed. Frame method F4 is not allowed. 7.5.16 Comment Record (COMENT) ┌─────┬───────────┬───────────┬────///────┬─────┐ │ │ │ │ │ │ │ REC │ Record │ Comment │ │ CHK │ │ TYP │ Length │ Type │ Comment │ SUM │ │ 88H │ │ │ │ │ │ │ │ │ │ │ └─────┴───────────┴───────────┴────///────┴─────┘ The COMENT record allows translators to include comments in object text. Comment Type The Comment Type field indicates the type of comment that this record carries, allowing you to structure comments for processes that selectively act on comments. The format of the Comment Type field is as follows: ┌───┬───┬───┬───┬───┬───┬───┬───┬──────────────────────┐ │ N │ N │ │ │ │ │ │ │ Comment │ │ P │ L │ 0 │ 0 │ 0 │ 0 │ 0 │ 0 │ Class │ └───┴───┴───┴───┴───┴───┴───┴───┴──────────────────────┘ The NP (NOPURGE) bit, if set to 1, indicates that this comment cannot be purged by object file utility programs that can delete Comment records. The NL (NOLIST) bit, if set to 1, indicates that the text in the Comment field should not appear in the listing file of object file utility programs that can list object Comment records. The Comment Class field is a byte defined as follows: ╓┌─┌──────────────────┌──────────────────────────────────────────────────────╖ Value Meaning ────────────────────────────────────────────────────────────────────────── 0 Language Translator Comment (obsolete) If the Comment field contains one of the strings "MS PASCAL" or "FORTRAN 77," then the Comment record enables the dsallocation switch on the Microsoft linker. Value Meaning ────────────────────────────────────────────────────────────────────────── linker. 156(9CH) DOS Version The Comment field contains a 2-byte integer that specifies the DOS level number. 157(9DH) Memory Model Indicates the memory model of the object module. The Comment field contains a single byte with the values S, M, L, or H, for SMALL, MEDIUM, LARGE, or HUGE, respectively. This Comment record is used only by the Microsoft XENIX linker. 158(9EH) Force Segment Ordering Causes the linker to use a special segment ordering for executable files. This Comment record has the same Value Meaning ────────────────────────────────────────────────────────────────────────── executable files. This Comment record has the same effect as giving the dosseg switch to Microsoft language versions of the linker. 159(9FH) Library Specifier 129(81H) Library Specifier (obsolete) Specifies a library to add to the Microsoft linker's library search list. The Comment field contains the name of the library. Notice that, unlike all other name specifications, the library name is not prefixed with its length but is determined by the record length. The nodefaultlibrarysearch switch causes the linker to ignore these Comment records. The 159(9FH) class record is ignored by XENIX versions of the Microsoft linker. 161(A1H) Microsoft Extensions Value Meaning ────────────────────────────────────────────────────────────────────────── Indicates that the object module contains extensions to the original Microsoft adaptation of the Intel Relocatable Object Module Format, such as the COMDEF ────────────────────────────────────────────────────────────────────────── Comment The Comment field provides the commentary information. 7.6 Microsoft Type Representations for Communal Variables ────────────────────────────────────────────────────────────────────────── Note Object modules not containing the COMENT record from the Microsoft Extensions class can represent communal variable definitions only with the obsolete method described here. Also, Microsoft language linkers earlier than version 3.05 can recognize this method only. The newer method uses the Communal Variable Definitions (COMDEF) record. ────────────────────────────────────────────────────────────────────────── A communal variable is defined in the object text by an EXTDEF record and the TYPDEF record to which it refers. The TYPDEF record of a communal variable has the following format: ┌─────┬────────┬───┬─────///────┬─────┐ │ REC │ Record │ │ Eight │ CHK │ │ TYP │ Length │ 0 │ Leaf │ SUM │ │ 8EH │ │ │ Descriptor │ │ └─────┴────────┴───┴─────///────┴─────┘ The Eight Leaf Descriptor field has the following format: ┌───┬────///─────┐ │ E │ Leaf │ │ N │ Descriptor │ └───┴────///─────┘ The EN bitfield specifies whether the next eight leaves in the Leaf Descriptor field are EASY (if EN = 0) or NICE (if EN = l). This byte is always zero for TYPDEFs of communal variables. The Leaf Descriptor field has one of the following two formats. The format for communal variables in the default data segment (NEAR variables) is as follows: ┌──────┬─────┬────///───┬─///────┐ │ NEAR │ VAR │ Length │ VAR │ │ 62H │ TYP │ In │ SUBTYP │ │ │ │ Bits │ │ └──────┴─────┴────///───┼──///───┤ │ │ └────────┘ (optional) The VARTYP (Variable Type) field may be either SCALAR (7BH), STRUCT (79H), or ARRAY (77H). The linker ignores the VAR SUBTYP field (if one exists). The format for communal variables not in the default data segment (FAR variables) is as follows: ┌─────┬─────┬────///───┬───///───┐ │ FAR │ VAR │ Number │ Element │ │ 61H │ TYP │ of │ Type │ │ │ 77H │ Elements │ Index │ └─────┴─────┴────///───┴───///───┘ The VARTYP field must be ARRAY (77H). The Length in Bits field specifies the Number of Elements, and the Element Type Index is an index to a previously defined TYPDEF record whose format is that of a NEAR communal variable. The format for the Length in Bits or Number of Elements fields is the same as the format of the Communal Length field of the COMDEF record. Link-Time Semantics All EXTDEF records referencing a TYPDEF record of one of the previously described formats are treated as communal variables. All others are treated as externally defined symbols for which a matching PUBDEF record is expected. For more information, see "Link-Time Semantics" in Section 7.5.8, "Communal Names Definition Record (COMDEF)." ──────────────────────────────────────────────────────────────────────────── Chapter 8 Programming Hints 8.1 Introduction 8.2 Interrupts 8.3 System Calls 8.4 Device Management 8.5 Memory Management 8.6 Process Management 8.7 File and Directory Management 8.7.1 Locking Files 8.8 Miscellaneous 8.1 Introduction This chapter describes recommended MS-DOS 4.0 programming procedures. By using these programming hints, you can ensure compatibility with future versions of MS-DOS. The hints are organized in the following categories: ■ Interrupts ■ System Calls ■ Device Management ■ Memory Management ■ Process Management ■ File and Directory Management ■ Miscellaneous 8.2 Interrupts ■ Never explicitly issue Interrupt 22H (Terminate Process Exit Address). Only the DOS should do this. To change the terminate address, use Function 35H (Get Interrupt Vector) to get the current address and save it, then use Function 25H (Set Interrupt Vector) to change the Interrupt 22H entry in the vector table to point to the new terminate address. ■ Use Interrupt 24H (Critical-Error-Handler Address) with care. The Interrupt 24H handler must preserve the ES register. An Interrupt 24H handler can issue only the system calls 01H-0CH. Making any other calls destroys the MS-DOS stack and prevents successful use of the Retry or Ignore options. When using the Retry or Ignore options, you must preserve the SS, SP, DS, BX, CX, and DX registers. ■ When an Interrupt 24H (Critical-Error-Handler Address) is received, always IRET back to MS-DOS with one of the standard responses. Programs that do not IRET from Interrupt 24H leave the system in an unpredictable state until a function call other than 01H-0CH is made. The Ignore option may leave incorrect or invalid data in internal system buffers. ■ Avoid trapping Interrupt 23H (CONTROL+C Handler Address) and Interrupt 24H (Critical-Error-Handler Address). Don't rely on trapping errors via Interrupt 24H as part of a copy protection scheme. These methods might not be included in future releases of MS-DOS. ■ A user program must never issue Interrupt 23H (CONTROL+C Handler Address). Only MS-DOS may issue Interrupt 23H. ■ Save any registers that your program uses before issuing Interrupt 25H (Absolute Disk Read) or Interrupt 26H (Absolute Disk Write). These interrupts destroy all registers except for the segment registers. Avoid writing or reading an interrupt vector directly to or from memory. ■ Use Functions 25H and 35H (Set Interrupt Vector and Get Interrupt Vector) to set and get values in the interrupt table. 8.3 System Calls ■ Use new system calls. Avoid using system calls that have been superseded by new calls unless the program must maintain backward compatibility with MS-DOS versions before 2.0. See Section 1.9, "Old System Calls," for a list of these new calls. ■ Avoid using functions 01H-0CH and 26H (Create New PSP). Use the new "tools" approach for reading and writing on standard input and output. Use Function 4B00H or 4B03H (Load and Execute Program or Overlay) instead of 26H to execute a child process. ■ Use file-sharing calls if more than one process is in effect. For more information, see "File Sharing" in Section 1.5.2, "File-Related Function Requests." ■ Use networking calls where appropriate. Some forms of IOCtl can only be used with Microsoft Networks. For more information and a list of these calls, see Section 1.6, "Microsoft Networks." ■ When selecting a disk with Function 0EH (Select Disk), treat the value returned in AL with care. The value in AL specifies the maximum number of logical drives; it does not specify which drives are valid. 8.4 Device Management ■ Use installable device drivers. MS-DOS provides a modular device driver structure for the BIOS, allowing you to configure and install device drivers at boot time. Block device drivers transmit a block of data at a time, while character device drivers transmit a byte of data at a time. Examples of both types of device drivers are given in Chapter 2, "MS-DOS Device Drivers." ■ Use buffered I/O. The device drivers can handle streams of data up to 64 kilobytes. To improve performance when sending a large amount of output to the screen, you can send it with one system call. ■ Programs that use direct console I/O via Function 06H and 07H (Direct Console I/O and Direct Console Input) and that want to read CONTROL+C as data should ensure that CONTROL+C checking is off. The program should ensure that CONTROL+C checking is off by using Function 33H (CONTROL+C Check). ■ Be compatible with international support. To provide support for international character sets, MS-DOS recognizes all possible byte values as significant characters in filenames and data streams. MS-DOS versions earlier than 2.0 ignored the high bit in the MS-DOS filename. 8.5 Memory Management ■ Use memory management. MS-DOS keeps track of allocated memory by writing a memory control block at the beginning of each area of memory. Programs should use Functions 48H (Allocate Memory), 49H (Free Allocated Memory), and 4AH (Set Block) to release unneeded memory. This allows for future compatibility. For more information, see Section 1.3, "Memory Management." ■ Use only allocated memory. Don't directly access memory that was not provided as a result of a system call. Do not use fixed addressing, use only relative references. A program that uses memory that has not been allocated to it may destroy other memory control blocks or cause other applications to fail. 8.6 Process Management ■ Use Function 4B00H or 4B03H (Load and Execute Program or Overlay, also known as EXEC) to load and execute programs. EXEC is the preferred call to use when loading programs and program overlays. Using the EXEC call instead of hard-coding information about how to load a .exe file (or always assuming that your file is a .com file) isolates your program from changes in .exe file formats and future releases of MS-DOS. ■ Use Function 31H (Keep Process), instead of Interrupt 27H (Terminate But Stay Resident). Function 31H allows programs that are greater than 64 kilobytes to terminate and stay resident. ■ Programs should terminate using Function 4CH (End Process). Programs that terminate by one of the following must ensure that the CS register contains the segment address of the PSP: ■ A long jump to offset 0 in the PSP ■ Issuing an Interrupt 20H with CS:0 pointing at the PSP ■ Issuing an Interrupt 21H with AH=0, CS:0 pointing at the PSP ■ A long call to location 50H in the PSP with AH=0 8.7 File and Directory Management ■ Use the MS-DOS file management system. Using the MS-DOS file system ensures program compatibility with future MS-DOS versions through compatible disk formats and consistent internal storage. ■ Use file handles instead of FCBs. A handle is a 16-bit number that MS-DOS returns when a file is opened or created using Functions 3CH, 3DH, 5AH, or 5BH (Create Handle, Open Handle, Create Temporary File, or Create New File). The MS-DOS file-related function requests that use handles are listed in Table 1.5 in Chapter 1, "System Calls." Although the default maximum number of open files is 20, this limit can be raised to 64K by Function 67H (Set Handle Count). For more information on this system call, see Chapter 1, "System Calls." You should use these calls instead of the old file-related functions that use FCBs (file control blocks). This is because a file operation can simply pass its handle rather than maintaining FCB information. If you must use FCBs, be sure the program closes them and does not move them around in memory. ■ Close files that have changed in length before issuing an Interrupt 20H (Program Terminate), Function 00H (Terminate Program), Function 4CH (End Process), or Function 0DH (Reset Disk). If you do not close a changed file, its length will not be recorded correctly in the directory. ■ Close files when they are no longer needed. Closing unneeded files increases efficiency in a networking environment. ■ If a program does use FCBs, that program should not close an FCB file and then continue writing to it. This practice will not work in a network environment and is not recommended under any circumstances. ■ Change disks only if all files on the disk are closed. If you don't close all the files, any information in internal system buffers may be written incorrectly to a changed disk. 8.7.1 Locking Files ■ Programs should not rely on being denied access to a locked region. To determine the status of a region, first attempt to lock it, then examine its error code. ■ Programs should not close a file with a locked region or terminate with an open file that contains a locked region. The result of this procedure is undefined. Programs that might be terminated by an Interrupt 23H or Interrupt 24H (CONTROL+C Handler Address or Critical-Error-Handler Address) should trap these interrupts and unlock any locked regions before exiting. 8.8 Miscellaneous ■ Avoid timing dependencies. Various machines use CPUs of different speeds. Also, programs that rely upon the speed of the clock for timing are not dependable in a networking environment. ■ Use the documented interface to the operating system. If either the hardware or media change, the operating system can use the features without modification. Don't use the ROM support provided by the OEM (Original Equipment Manufacturer). Don't directly address the video memory. Don't use undocumented function calls, interrupts, or features. These items may change or may not exist in future MS-DOS versions. If you do use these features, you will make your program highly non-portable. ■ Use the .exe format rather than the .com format. .Exe files are relocatable; .com files are direct memory images that load at a specific place and have no room for additional control information. .Exe files have headers that can be expanded for compatibility with future MS-DOS versions. ■ Use the environment to pass information to applications. The environment allows a parent process to pass information to a child process. The command.com file is usually the parent process to every application, so it can easily pass default drive and path information to the application. ──────────────────────────────────────────────────────────────────────────── Index Numbers 80186 microprocessor 80286 microprocessor 8086 microprocessor 8086 object language 8086 object module format. See Object Module Formats (OMF) A Absolute Disk Read (Interrupt 25H) Absolute Disk Write (Interrupt 26H) Absolute segment, LSEG ACBP byte, SEG ATTR Address mode Alignment attribute Alignment subfield, SEG ATTR Allocate Memory (Function 48H) Application Frame Number, protected-mode Archive bit Array, character ASCII character set ASCIZ string Assign list Attribute primary secondary Target Attribute byte Attribute field Attribute, LSEG Alignment Combination SEG ATTR field, SEGDEF AUTOEXEC file Auxiliary Input (Function 03H) Auxiliary Output (Function 04H) B base, definition Big subfield, SEG ATTR BIN format file Binary line number BIOS Parameter ^Block (BPB) BIOS Parameter Block (BPB) Bit 8 Bit 9 Bitfield Block Count subfield, Iterated Data Block Block devices device drivers disk drives example installation Boot sector BPB pointer Buffered Keyboard Input (Function 0AH) BUILD BPB Build BPB Busy bit Byte, representation C C language CALL instruction Cancel Assign-List Entry (Function 5FH, Code 04H) Canonic Frame Canonic Frame, definition Carry flag Case-Mapping Call Change Current Directory (Function 3BH) Change Directory Entry (Function 56H) Character array Character device driver, example Character devices Character set definition Check Keyboard Status (Function 0BH) CHKSUM field, SAMREC Class Name, definition CLOCK device Close File (Function 10H) Close Handle (Function 3EH) Cluster Code page definition Code segment, CS Combination attribute Combination subfield, SEG ATTR COMDEF record field CHKSUM Communal Length, repeated Communal Name, repeated Data Segment Type, repeated Record Length RECTYP Type Index, repeated length fields, format order with respect to COMENT purpose schematic COMENT record field CHKSUM Comment Comment Type Record Length RECTYP order with respect to COMDEF order with respect to LOCSYM purpose schematic subfield of Comment Type Comment Class Command code field Command processor Command.com Commands, utility, NLS Comment class subfield, Comment Type Comment field, COMENT Comment record Comment Record (COMENT) Comment Type field, COMENT bit settings definition format Commit File (Function 68H) Common blocks, FORTRAN Communal Length field, COMDEF Communal Name field, COMDEF Communal Name, ordering with External Name Communal names definition record. See COMDEF record Communal Names Definition Record (COMDEF) Communal variable FAR HUGE NEAR similarity to FORTRAN common block uninitialized public variable Compatibility, ensuring Complete Name, definition Computer language C FORTRAN COMSPEC Con device config.sys config.sys file Content subfield, Iterated Data Block Control blocks Control information CONTROL+C Address (Interrupt 23H) CONTROL+C Check (Function 33H) CONTROL+C Handler Address (Interrupt 23H) Country code definition Country code, current Country-dependent information case conversion tables collating sequence, character sorting currency date DBCS environmental vector keyboard support time valid single-byte characters Country-dependent information, NLS Country.sys file Create Directory (Function 39H) Create File (Function 16H) Create Handle (Function 3CH) Create New File (Function 5BH) Create New PSP (Function 26H) Create Temporary File (Function 5AH) Critical Error Handler Address (Interrupt 24H) CS register D DAT field, LEDATA Data Record Data segment DS ES FAR NEAR Data Segment Type field, COMDEF Delete Directory Entry (Function 41H) Delete File (Function 13H) Descriptor, Group Component, GRPDEF Device control Device drivers block creating example installable installing non-resident preserving registers resident Device Handles Device header Device interrupt routine Device management, programming hints Device strategy routine Device-related function requests Direct Console Input (Function 07H) Direct Console I/O (Function 06H) Directory Entry Directory-Related Function Requests Directory-related function requests Disk allocation Disk Directory Disk formats IBM standard MS-DOS Disk Transfer Address (DTA) Dispatch table Display Character (Function 02H) Display String (Function 09H) Done bit DS register Duplicate File Handle (Function 45H) E Eight Leaf Descriptor field, TYPDEF format subfield EN Leaf Descriptor Element Type Index subfield, Leaf Descriptor EN subfield, Eight Leaf Descriptor End address End Process (Function 4CH) Enumerated Data Offset field, LEDATA Error bit Error codes Error Handling Error handling ES register EXE device drivers .exe files exe files EXE format file EXE loader EXTDEF record field CHKSUM External Name, repeated Record Length RECTYP Type Index, repeated purpose schematic Extended error codes Extended FCB Extensions class, Microsoft External Index External indices External Name mapping referenced in FIXUPP record External Name field, EXTDEF External names definition record. See EXTDEF record External Names Definition Record (EXTDEF) F FAR data segment FAR subfield, Leaf Descriptor FAR variable format, Leaf Descriptor FAT FAT ID byte FAT ID byte FBVAL, definition FCB File Allocation Table File and directory management, programming hints File attributes File Control Block definition extended fields format opened unopened File locking, programming hints Filename separators Filename terminators File-related function requests File-sharing function requests Find First File (Function 4EH) Find Next File (Function 4FH) FIX DAT subfield, Fixup internal structure schematic Fixup definition Frame Location segment-relative self-relative Target Fixup field, FIXUPP data type Frame Location Mode Target definition schematic subfield LOCAT Fixup mode segment-relative self-relative FIXUP record FIXUPP record External Name referenced in field CHKSUM Fixup, repeated Frame Datum, conditional Record Length RECTYP Target Datum, conditional Thread, repeated purpose schematic subfield of FIX DAT, Fixup F Frame P T TARGT subfield of Fixup Frame Datum, conditional Target Datum, conditional Target Displacement, conditional subfield of LOCAT, Fixup Data Record Offset LOC M (mode) subfield of Thread Index, conditional TRD DAT subfield of TRD DAT, Thread D Method THRED FIXUPP Record (FIXUPP) Flush Flush Buffer, Read Keyboard (Function 0CH) Force Duplicate File Handle (Function 46H) Format FORTRAN, common blocks FORTRAN language FOVAL, definition Frame definition Frame Number nomenclature specifying specifying, FIXUPP Frame Datum field, FIXUPP Frame Datum subfield, Fixup External Index Group Index Segment Index Frame Datum subfield, START ADDRS Frame Number Frame Number, conditional Frame Number, definition Frame Number subfield, Public Base Frame Number subfield, SEG ATTR Frames Thread Number, FIXUPP Free Allocated Memory (Function 49H) Function Requests alphabetic order calling definition device-related Directory-related directory-related file-related file-sharing Function 00H Function 01H Function 02H Function 03H Function 04H Function 05H Function 06H Function 07H Function 08H Function 09H Function 0AH Function 0BH Function 0CH Function 0DH Function 0EH Function 0FH Function 10H Function 11H Function 12H Function 13H Function 14H Function 15H Function 16H Function 17H Function 19H Function 1AH Function 1BH Function 1CH Function 21H Function 22H Function 23H Function 24H Function 25H Function 26H Function 27H Function 28H Function 29H Function 2AH Function 2BH Function 2CH Function 2DH Function 2EH Function 2FH Function 30H Function 31H Function 33H Function 35H Function 36H Function 38H Function 39H Function 3AH Function 3BH Function 3CH Function 3DH Function 3EH Function 3FH Function 40H Function 41H Function 42H Function 43H Function 44H, Code 08H Function 44H, Code 09H Function 44H, Code 0AH Function 44H, Code 0BH Function 44H, Code 0CH Function 44H, Code 0DH Function 44H, Codes 00H and 01H Function 44H, Codes 02H and 03H Function 44H, Codes 04H and 05H Function 44H, Codes 06H and 07H Function 44H, Codes 0EH and 0FH Function 45H Function 47H Function 48H Function 49H Function 4AH Function 4BH, Code 00H Function 4BH, Code 03H Function 4CH Function 4DH Function 4EH Function 4FH Function 54H Function 56H Function 57H Function 58H Function 59H Function 5AH Function 5BH Function 5CH, Code 00H Function 5CH, Code 01H Function 5EH, Code 00H Function 5EH, Code 02H Function 5FH, Code 02H Function 5FH, Code 03H Function 5FH, Code 04H Function 62H Function 65H Function 66H Function 67H Function 68H Handling errors memory management National Language Support Network-related network-related numeric order process management standard character I/O system-management Function requests definition Function 25H Function 35H Function 46H G Generic IOCtl for devices (Function 44H, Code 0DH) Generic IOCtl for handles (Function 44H, Code 0CH) Generic IOCtl Function Get Assign List Entry (Function 5FH, Code 02H) Get Country Data (Function 38H) Get Current Directory (Function 47H) Get Current Disk (Function 19H) Get Date (Function 2AH) Get Default Drive Data (Function 1BH) Get Disk Free Space (Function 36H) Get Disk Transfer Address (Function 2FH) Get Drive Data (Function 1CH) Get Extended Country Information (Function 65H) Get Extended Error (Function 59H) Get File Size (Function 23H) Get Interrupt Vector (Function 35H) Get Machine Name (Function 5EH, Code 00H) Get MS-DOS Version Number (Function 30H) Get PSP (Function 62H) Get Return Code Child Process (Function 4DH) Get Time (Function 2CH) Get Verify State (Function 54H) Get/Set Allocation Strategy (Function 58H) Get/Set Date/Time of File (Function 57H) Get/Set File Attributes (Function 43H) Get/Set Global Code Page (Function 66H) Get/Set IOCtl Drive Map (Function 44H, Codes 0EH and 0FH) Get/Set Logical Drive Map Function Group Component Descriptor field, GRPDEF Group, definition Group definition record. See GRPDEF record Group Definition Record (GRPDEF) Group Index Group Index subfield, Line Number Base Group Index subfield, Public Base Group Name Index field, GRPDEF GRPDEF record definition field CHKSUM Group Component Descriptor, repeated Group Name Index Record Length RECTYP schematic H Handles definition device Handling errors Header hibyte, definition Hidden files High-Level Language HUGE communal variable I IBM disk format Index definition Index fields Index Number Index subfield, Thread External Index Group Index Segment Index Indices Indices, external Init INIT code Installable device drivers Instruction CALL JUMP SHORT-JUMP Instruction Pointer (IP) Internal stack Interrupt entry point Interrupt handlers Interrupt routines Interrupt-handling routine Interrupts 21H Address of handlers alphabetic order definition Interrupt 20H Interrupt 21H Interrupt 22H Interrupt 23H Interrupt 24H Interrupt 25H Interrupt 26H Interrupt 27H issuing numeric order programming hints Vector table I/O Control for Devices (Function 44H) IOCtl IOCtl bit IOCtl Block (Function 44H, Codes 4 and 5) IOCtl Character (Function 44H, Codes 2 and 3) IOCtl Data (Function 44H, Codes 0 and 1) IOCtl Is Changeable (Function 44H, Code 08H) IOCtl Is Redirected Block (Function 44H, Code 09H) IOCtl Is Redirected Handle (Function 44H, Code 0AH) IOCtl Retry (Function 44H, Code 0BH) IOCtl Status (Function 44H, Codes 6 and 7) io.sys file IP. See Instruction Pointer (IP) Iterated Data Block field, LIDATA Iterated Data Offset field, LIDATA J JUMP instruction K Keep Process (Function 31H) Keyboard layouts, national, NLS L Language C FORTRAN Leaf Descriptor subfield, Eight Leaf Descriptor format FAR variable NEAR variable subfield NEAR VARTYP LEDATA field CHKSUM Record Length RECTYP purpose LEDATA record field DAT, repeated Enumerated Data Offset Segment Index schematic Length fields, COMDEF, format Length in Bits subfield, Leaf Descriptor Length of Record Field LHEADR record field CHKSUM L-module Name Record Length RECTYP schematic LIDATA record field CHKSUM Iterated Data Block, repeated Iterated Data Offset Record Length RECTYP Segment Index purpose schematic subfield of Iterated Data Block Block Count Content Repeat Count Line Number Base field, LINNUM Line number, binary Line Number field, LINNUM Line Number Offset field, LINNUM Line Numbers Record (LINNUM) LINK Linker, Microsoft Linker, Microsoft Link-time semantics LINNUM record field CHKSUM Line Number Base Line Number Offset, repeated Line Number, repeated Record Length RECTYP purpose schematic subfield of Line Number Base Group Index Segment Index List of Names Record (LNAMES) L-module Header Record (LHEADR) L-module Name LNAMES record field CHKSUM Name, repeated Record Length RECTYP schematic Load and Execute Program (Function 4BH, Code 00H) Load module Load Overlay (Function 4BH, Code 03H) Loadsize lobyte, definition Local Base field, LOCSYM Local buffering Local Name field, LOCSYM Local Offset field, LOCSYM Local symbol Local Symbols Record (LOCSYM) LOCAT subfield, Fixup internal structure schematic Location types base hibyte lobyte offset pointer Lock (Function 5CH, Code 00H) LOCSYM record field CHKSUM Local Base Local Name, repeated Local Offset, repeated Record Length RECTYP Type Index, repeated order with respect to COMENT purpose schematic Logical Enumerated Data Record (LEDATA) Logical Iterated Data Record (LIDATA) Logical sector Logical sector numbers Logical Segment. See LSEG LSEG absolute Combination attribute Alignment attribute absolute segment relocatable segment canonic Frame Class name Combination attribute absolute segment relocatable segment combining Complete name definition Overlay Name relocatable byte-aligned Combination attribute page-aligned paragraph-aligned word-aligned Segment Name M Make Assign-List Entry (Function 5FH, Code 03H) Mapping logical to physical starting address MAS. See Memory Address Space (MAS) MATTR subfield, MOD TYP Maxalloc Media Check Media descriptor byte Media, determining Memory address Memory Address Space (MAS) Memory control block Memory image, 8086 Memory image, LSEGs in Memory image, relocatable Memory management function requests Memory management, programming hints Memory model huge large medium small Microprocessor 80186 80286 8086 Microsoft Extensions class Microsoft linker Microsoft linker Microsoft Networks Microsoft Networks Manager's Guide Microsoft Networks User's Guide Minalloc MOD TYP field, MODEND MATTR subfield module attributes Mode fixup segment-relative self-relative Mode, address MODEND record field CHKSUM MOD TYP Record Length RECTYP START ADDRS, conditional purpose schematic subfield of START ADDRS Frame Datum, conditional Target Datum, conditional Target Displacement, conditional Module record ordering in Module, definition Module End Record (MODEND) Module header record, definition Move File Pointer (Function 42H) MS-DOS, 8086 object language MS-DOS initialization MS-DOS memory map MS-DOS User's Reference msdos.sys file Multitasking N Name field Name field, SAMREC Name Indices National keyboard layouts, NLS National Language Support Function Requests National Language Support (NLS) restrictions unsupported features National Language Support system calls NEAR data segment NEAR subfield, Leaf Descriptor NEAR variable format, Leaf Descriptor Network-related Function Requests Network-related function requests Non IBM format bit Non-destructive Read No Wait NUL device Number field, SAMREC Number of Elements subfield, Leaf Descriptor O Object language, 8086 Object module restrictions Object Module Formats Object Module Formats (OMF) offset, definition Offset subfield, SEG ATTR Old system calls OMF. See Object Module Formats (OMF) Open File (Function 0FH) Open Handle (Function 3DH) Opened FCB Operating system MS-DOS PC-DOS XENIX Overlay Name, definition P Parameter block Parse File Name (Function 29H) Path command PC-DOS, 8086 object language Physical Segment. See PSEG Pointer to Next Device field Predefined device handles Print Character (Function 05H) Printer Setup (Function 5EH, Code 02H Process management function requests Process management, programming hints Processor. See Microprocessor Program End Process (Interrupt 20H) Program segment Program Segment Prefix Programming hints device management file and directory management file locking interrupts memory management miscellaneous process management recommendations system calls Programming interfaces, NLS Prompt command Protected-mode application Frame Number PSEG definition PUBDEF record field Public Base, repeated Public Name, repeated Public Offset, repeated Record Length RECTYP Type Index, repeated purpose schematic subfield of Public Base Frame Number, conditional subfield, Public Base Frame Number, conditional Group Index Segment Index Public Base field, PUBDEF Public Name field, PUBDEF Public names definition record. See PUBDEF record Public Names Definition Record (PUBDEF) Public Offset field, PUBDEF Public symbol Public variable R Random Block Read (Function 27H) Random Block Write (Function 28H) Random Read (Function 21H) Random Write (Function 22H) Read Handle (Function 3FH) Read Keyboard and Echo (Function 01H) Read Keyboard (Function 08H) Read Only Memory Read or Write Record COMDEF COMENT comment Data EXTDEF FIXUP FIXUPP GRPDEF LEDATA LHEADR LIDATA LINNUM LNAMES LOCSYM MODEND PUBDEF RECTYP(record type) SAMREC (sample record) SEGDEF symbol definition COMDEF EXTDEF PUBDEF THEADR TYPDEF Record format abbreviation bitfields conditional field repeated field sample (SAMREC) SAMREC (sample record) CHKSUM field Name field Number field Record Length field SAMREC(sample record) RECTYP field title Record formats Record Length field, SAMREC Record order definition semantic rules syntax Record Size RECTYP(record type)field Reference segment-relative Reference self-relative References WIRTH CACM, Nov. 1977) Register CS DS ES SS Registers, treatment of Relocatable memory image Relocatable segment, LSEG Relocation information Relocation item offset value to a word in the load Relocation table Remove Directory (Function 3AH) Rename File (Function 17H) Repeat Count subfield, Iterated Data Block request header Request packet Reset Disk (Function 0DH) Resident device drivers ROM Root directory S SAMREC (sample record) schematic Search for First Entry (Function 11H) Search for Next Entry (Function 12H) Sector count SEG ATTR field, SEGDEF SEGDEF record definition field CHKSUM Class Name Index Overlay Name Index Record Length RECTYP SEG ATTR Segment Name Index schematic subfield of SEG ATTR Alignment Big Combination Offset, conditional SEGDEF recrod field Segment Length Segment absolute, LSEG attribute Alignment Combination logical (LSEG) physical (PSEG) relocatable, LSEG Segment addressing Segment definition record. See SEGDEF record Segment Definition Record (SEGDEF) Segment Index Segment Index field, LEDATA Segment Index field, LIDATA Segment Index subfield, Group Component Descriptor Segment Index subfield, Line Number Base Segment Index subfield, Public Base Segment Length field, SEGDEF Segment Name, definition Segment Name Index field, SEGDEF Segment-relative fixup Segment-relative reference Select Disk (Function 0EH) Self-relative fixup Self-relative reference Semantic rules, record ordering Semantics, link-time Sequential Read (Function 14H) Sequential Write (Function 15H) Set Block (Function 4AH) Set command Set Country Data (Function 38H) Set Date (Function 2BH) Set Disk Transfer Address (Function 1AH) Set Handle Count(Function 67H) Set Interrupt Vector (Function 25H) Set Relative Record (Function 24H) Set Time (Function 2DH) Set/Reset Verify Flag (Function 2EH) SHORT-JUMP instruction SS register Stack segment, SS Standard character I/O function requests START ADDRS field, MODEND Format Start sector Start segment value the relocation item offset static request header Status Status field Strategy entry point Strategy routines Subfield Comment Type Comment Class Eight Leaf Descriptor EN Leaf Descriptor Fixup Frame Datum Target Datum Target Displacement Frame Number, conditional Group Component Descriptor Segment Index Iterated Data Block Block Count Content Repeat Count Leaf Descriptor Element Type Index FAR Length in Bits NEAR Number of Elements VAR SUBTYP VARTYP Line Number Base, LINNUM Group Index Segment Index MOD TYP MATTR Public Base Group INdex SEG ATTR Alignment Big Combination Segment Index START ADDRS Frame Datum Target Datum Target Displacement Thread Index TRD DAT Subfield OFFH Superseded system calls Symbol local public Symbol definition Symbol definition record COMDEF EXTDEF PUBDEF Syntax, record ordering Sysinit System call National Language Support: System Calls superseded calls System calls definition programming hints replacements for old types of System files System prompt System-management function requests T Target definition nomenclature specification attribute specifying specifying, FIXUPP Thread Number, FIXUPP Target Datum field, FIXUPP Target Datum subfield, Fixup External Index Group Index Segment Index Target Datum subfield, START ADDRS Target Displacement subfield, Fixup Target Displacment subfield, START ADDRS Terminate But Stay Resident (Interrupt 27H) Terminate Process Exit Address (Interrupt 22H) Terminate Program (Function 00H) THEADR record field CHKSUM Record Length RECTYP T-module Name schematic Thread Data subfield. See TRD DAT subfield, Thread Thread field, FIXUPP data type Frame Target definition Thread Number, THRED T-module, definition T-module Header Record (THEADR) T-Module Name Transfer address TRD DAT subfield, Thread D subfield internal structure Method subfield schematic THRED subfield TYPDEF record communal variable field CHKSUM Eight Leaf Descriptor Record Length RECTYP subfield of Eight Leaf Descriptor EN subfield of Leaf Descriptor Element Type Index FAR Length in Bits NEAR Number of Elements VAR SUBTYP, optional VARTYP Type Index field, COMDEF Type Index field, EXTDEF Type Index field, LOCSYM Type Index field, PUBDEF Type-ahead buffer U Unit code field Unlock (Function 5CH, Code 01H) Unopened FCB User Stack User stack Utility commands, NLS V VAR SUBTYP subfield, Leaf Descriptor Variable communal FAR HUGE" NEAR public VARTYP subfield, Leaf Descriptor ARRAY SCALAR STRUCT Vector table Volume ID Volume label W Wildcard characters Write Handle (Function 40H) X XENIX, 8086 object language