|
|
| (4 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| <PRE>
| | The '''DOS 4.00 Technical Reference and Application Programming''' is an additional purchase item written for programmer's who develop applications for IBM Personal Computers and Personal System/2. |
| DOS 4.00: TECHNICAL REFERENCE AND APPLICATION PROGRAMMING | | :15F0256 |
|
| | :1988 |
| August 6th, 1988
| |
|
| |
| FIRST EDITION (JULY 1988)
| |
|
| |
| (c) Copyright International Business Machines Corporation 1981, 1988
| |
| All rights reserved.
| |
|
| |
| PREFACE
| |
|
| |
| AUDIENCE
| |
|
| |
| This book is written for programmers who develop applications for IBM
| |
| Personal Computers and Personal System/2(R) computers.(1) | |
|
| |
| The program developer should be competent on the IBM Personal Computer and/or
| |
| the Personal System/2 and should be familiar with DOS and at least one
| |
| personal computer programming language.
| |
|
| |
| CONTENT
| |
|
| |
| Some parts of the book have been rewritten and reorganized to make reference
| |
| and system architecture information more concise and to present programming
| |
| information in a task-oriented manner. Information about new and enhanced
| |
| functions has been added, providing some guide material.
| |
|
| |
| RELATED PUBLICATIONS
| |
|
| |
| Other manuals that provide detailed information about DOS 4.00 are:
| |
|
| |
| Getting Started with DOS 4.00
| |
| Using DOS 4.00
| |
| DOS 4.00 Command Reference
| |
| IBM Keyboard Layouts for Your PC and PS/2 systems.
| |
|
| |
|
| |
| (1) Personal System/2 is a registered trademark of the International Business
| |
| Machines Corporation.
| |
|
| |
| CONTENTS
| |
|
| |
| CHAPTER 1. INTRODUCTION TRD41 7
| |
| Organization of this Book TRD41 16
| |
| New DOS 4.00 Services TRD41 43
| |
| The Utilities Diskette TRD41 57
| |
| Minimum Hardware Configuration TRD41 79
| |
| CHAPTER 2. ACCESSING DISKS TRD42 11
| |
| The Disk Format TRD42 20
| |
| The Boot Record TRD42 41
| |
| The File Allocation Table (FAT) TRD42 49
| |
| The Disk Directory TRD42 114
| |
| The Data Area TRD42 143
| |
| Accessing the Disk TRD42 150
| |
| Reading and Writing Data Directly to the Disk TRD42 168
| |
| Requesting Drive and Disk Information TRD42 180
| |
| CHAPTER 3. ACCESSING FILES WITH FILE HANDLES TRD43 13
| |
| Filenames TRD43 48
| |
| File Handles TRD43 62
| |
| Special File Handles TRD43 88
| |
| Reading and Writing Data to a File TRD43 119
| |
| Requesting and Specifying File Attributes TRD43 140
| |
| Accessing Subdirectories TRD43 152
| |
| Accessing Directories TRD43 266
| |
| Finding Files in Directories TRD43 282
| |
| Requesting and Specifying National Language Support (NLS) TRD43 294
| |
| Controlling Network Operations TRD43 307
| |
| CHAPTER 4. ACCESSING FILES USING FILE CONTROL BLOCKS TRD44 10
| |
| The File Control Block (FCB) TRD44 21
| |
| The Extended FCB TRD44 128
| |
| The Disk Transfer Area (DTA) TRD44 149
| |
| Accessing Files TRD44 172
| |
| Accessing Sequential Records TRD44 218
| |
| Accessing Random Records TRD44 231
| |
| Finding Files in Directories TRD44 250
| |
| CHAPTER 5. MANAGING DEVICE I/O TRD45 9
| |
| Managing Display I/O TRD45 20
| |
| Managing Keyboard I/O TRD45 43
| |
| Managing Miscellaneous I/O TRD45 71
| |
| Managing File System Activities TRD45 84
| |
| Accessing the System Device Drivers' Control Channel TRD45 105
| |
| Reading and Writing Data in Binary and ASCII Modes TRD45 155
| |
| CHAPTER 6. CONTROLLING PROCESSES TRD46 17
| |
| Allocating Memory TRD46 32
| |
| DOS 4.00 Memory Management TRD46 47
| |
| The DOS 4.00 Memory Map TRD46 71
| |
| Identifying a Program at Load Time TRD46 134
| |
| The Program Segment TRD46 147
| |
| Loading and Executing Overlays TRD46 198
| |
| The Parameter Block TRD46 216
| |
| Terminating a Program/Subprogram TRD46 260
| |
| Loading an Overlay without Executing It TRD46 307
| |
| Calling a Command Processor TRD46 328
| |
| Responding to Errors TRD46 352
| |
| Responding to a Control-Break Action TRD46 379
| |
| Requesting and Specifying the System Date and Time TRD46 411
| |
| Requesting and Specifying the Interrupt Vectors TRD46 426
| |
| CHAPTER 7. CREATING OBJECT CODE LIBRARIES TRD47 15
| |
| The IBM Library Manager/2 TRD47 20
| |
| Starting the LIB.EXE Utility TRD47 52
| |
| Entering Input at the Command Line TRD47 216
| |
| Using a Response File TRD47 308
| |
| Creating and Maintaining Libraries TRD47 359
| |
| Creating a Library File TRD47 364
| |
| Modifying a Library File TRD47 395
| |
| Combining Libraries TRD47 457
| |
| Creating a Cross-Reference Listing TRD47 475
| |
| Performing Consistency Checks TRD47 500
| |
| Setting the Library Page Size TRD47 513
| |
| Library Manager Error Messages TRD47 540
| |
| CHAPTER 8. CREATING AN EXECUTABLE FILE TRD48 35
| |
| The IBM Linker/2 TRD48 40
| |
| Starting the LINK.EXE Program TRD48 56
| |
| Entering LINK Input at the Command Line TRD48 246
| |
| Using a Response File to Supply LINK Input TRD48 340
| |
| Using Linker Options TRD48 436
| |
| Preparing Files for CodeView /CODEVIEW TRD48 512
| |
| Reserving Paragraph Space /CPARMAXALLOC TRD48 530
| |
| Ordering Segments /DOSSEG TRD48 560
| |
| Controlling Data Loading /DSALLOCATE TRD48 583
| |
| Packing Executable Files /EXEPACK TRD48 607
| |
| Viewing the Options List /HELP TRD48 640
| |
| Controlling Run File Loading /HIGH TRD48 661
| |
| Displaying LINK-Time Information /INFORMATION TRD48 679
| |
| Copying Line Numbers to the Map File /LINENUMBERS TRD48 692
| |
| Producing a Public Symbol Map /MAP TRD48 731
| |
| Ignoring Default Libraries /NODEFAULTLIBRARYSEARCH TRD48 770
| |
| Preserving Compatibility /NOGROUPASSOCIATION TRD48 793
| |
| Preserving Lowercase /NOIGNORECASE TRD48 807
| |
| Setting the Overlay Interrupt /OVERLAYINTERRUPT TRD48 836
| |
| Pausing to Change Disks /PAUSE TRD48 856
| |
| Setting the Maximum Number of Segments /SEGMENTS TRD48 900
| |
| Setting the Stack Size /STACK TRD48 939
| |
| Reading the Map File TRD48 976
| |
| Creating an Overlaid Version of Your Program TRD48 1032
| |
| Specifying an Overlay Structure to LINK TRD48 1050
| |
| How LINK Formats the .EXE File TRD48 1075
| |
| Ordering Segments TRD48 1083
| |
| Segment Combine-Types TRD48 1106
| |
| Groups TRD48 1143
| |
| Instruction and Data Reference Errors TRD48 1159
| |
| Linker Error Messages TRD48 1215
| |
| Linker Limits TRD48 1681
| |
| CHAPTER 9. CONVERTING FILE FORMATS TRD49 8
| |
| The EXE2BIN.EXE Utility TRD49 13
| |
| Entering Input to EXE2BIN TRD49 34
| |
| Two Types of Conversion TRD49 61
| |
| Device Drivers TRD49 66
| |
| Standard .COM File TRD49 100
| |
| CHAPTER 10. DEBUGGING A PROGRAM TRD410 32
| |
| The DEBUG Utility TRD410 37
| |
| Starting the DEBUG.COM Program TRD410 46
| |
| Entering Commands at the DEBUG Prompt TRD410 67
| |
| DEBUG Command Summary TRD410 103
| |
| The DEBUG Work Space TRD410 181
| |
| A (Assemble) Command TRD410 225
| |
| C (Compare) Command TRD410 348
| |
| D (Dump) Command TRD410 400
| |
| E (Enter) Command TRD410 504
| |
| F (Fill) Command TRD410 620
| |
| G (Go) Command TRD410 669
| |
| H (Hexarithmetic) Command TRD410 771
| |
| I (Input) Command TRD410 789
| |
| L (Load) Command TRD410 811
| |
| M (Move) Command TRD410 919
| |
| N (Name) Command TRD410 973
| |
| O (Output) Command TRD410 1019
| |
| P (Proceed) Command TRD410 1040
| |
| Q (Quit) Command TRD410 1090
| |
| R (Register) Command TRD410 1113
| |
| S (Search) Command TRD410 1263
| |
| T (Trace) Command TRD410 1321
| |
| U (Unassemble) Command TRD410 1390
| |
| W (Write) Command TRD410 1513
| |
| XA (EMS Allocate) Command TRD410 1645
| |
| XD (EMS Deallocate) Command TRD410 1672
| |
| XM (EMS Map) Command TRD410 1699
| |
| XS (EMS Status) Command TRD410 1727
| |
| DEBUG Error Messages TRD410 1759
| |
| CHAPTER 11. WRITING AN INSTALLABLE DEVICE DRIVER TRD411 26
| |
| Types of Device Drivers TRD411 39
| |
| Character Device Drivers TRD411 48
| |
| Block Device Drivers TRD411 55
| |
| How DOS 4.00 Installs Device Drivers TRD411 84
| |
| The Basic Parts of a Device Driver TRD411 134
| |
| The Device Driver Header TRD411 148
| |
| The Strategy Routine TRD411 274
| |
| The Interrupt Routines TRD411 283
| |
| How DOS 4.00 Passes a Request TRD411 300
| |
| Responding to Requests TRD411 392
| |
| Initialization Request TRD411 456
| |
| Media Check Request TRD411 511
| |
| Build BPB Request TRD411 630
| |
| Input and Output Requests TRD411 815
| |
| Nondestructive Input No Wait Request TRD411 879
| |
| Character Input and Output Status Requests TRD411 901
| |
| Character Input and Output Flush Requests TRD411 935
| |
| Open and Close Requests TRD411 951
| |
| Removable Media Request TRD411 983
| |
| Generic IOCTL Request TRD411 1008
| |
| Get Logical Device Request TRD411 1037
| |
| Set Logical Device Request TRD411 1055
| |
| CLOCK$ Device Driver Example TRD411 1073
| |
| APPENDIX A. DOS 4.00 INTERRUPTS TRD412 13
| |
| 20H Program Terminate TRD412 21
| |
| 21H Function Request TRD412 41
| |
| 22H Terminate Address TRD412 46
| |
| 23H Ctrl-Break Exit Address TRD412 53
| |
| 24H Critical Error Handler Vector TRD412 83
| |
| 25H/26H Absolute Disk Read/Write TRD412 287
| |
| 27H Terminate but Stay Resident TRD412 353
| |
| 28H-2EH Reserved for DOS 4.00 TRD412 392
| |
| 2FH Multiplex Interrupt TRD412 396
| |
| 30H-3FH Reserved for DOS 4.00 TRD412 695
| |
| APPENDIX B. DOS 4.00 FUNCTION CALLS TRD413 100
| |
| Using DOS 4.00 Function Calls TRD413 219
| |
| Program Code Fragments TRD413 230
| |
| .COM Programs TRD413 236
| |
| DOS 4.00 Registers TRD413 256
| |
| Responding to Errors TRD413 340
| |
| Extended Error Codes TRD413 355
| |
| 00H -- Program Terminate TRD413 518
| |
| 01H -- Console Input with Echo TRD413 546
| |
| 02H -- Display Output TRD413 581
| |
| 03H -- Auxiliary Input TRD413 603
| |
| 04H -- Auxiliary Output TRD413 631
| |
| 05H -- Printer Output TRD413 655
| |
| 06H -- Direct Console I/O TRD413 672
| |
| 07H -- Direct Console Input Without Echo TRD413 720
| |
| 08H -- Console Input Without Echo TRD413 753
| |
| 09H -- Display String TRD413 786
| |
| 0AH -- Buffered Keyboard Input TRD413 815
| |
| 0BH -- Check Standard Input Status TRD413 848
| |
| 0CH -- Clear Keyboard Buffer and Invoke a Keyboard Function TRD413 868
| |
| 0DH -- Disk Reset TRD413 885
| |
| 0EH -- Select Disk TRD413 904
| |
| 0FH -- Open File TRD413 937
| |
| 10H -- Close File TRD413 985
| |
| 11H -- Search for First Entry TRD413 1022
| |
| 12H -- Search for Next Entry TRD413 1099
| |
| 13H -- Delete File TRD413 1149
| |
| 14H -- Sequential Read TRD413 1193
| |
| 15H -- Sequential Write TRD413 1240
| |
| 16H -- Create File TRD413 1286
| |
| 17H -- Rename File TRD413 1330
| |
| 19H -- Current Disk TRD413 1380
| |
| 1AH -- Set Disk Transfer Address TRD413 1400
| |
| 1BH -- Allocation Table Information TRD413 1425
| |
| 1CH -- Allocation Table Information for Specific Device TRD413 1453
| |
| 21H -- Random Read TRD413 1489
| |
| 22H -- Random Write TRD413 1541
| |
| 23H -- File Size TRD413 1599
| |
| 24H -- Set Relative Record Field TRD413 1642
| |
| 25H -- Set Interrupt Vector TRD413 1668
| |
| 26H -- Create New Program Segment TRD413 1695
| |
| 27H -- Random Block Read TRD413 1725
| |
| 28H -- Random Block Write TRD413 1787
| |
| 29H -- Parse Filename TRD413 1847
| |
| 2AH -- Get Date TRD413 1918
| |
| 2BH -- Set Date TRD413 1946
| |
| 2CH -- Get Time TRD413 1979
| |
| 2DH -- Set Time TRD413 2015
| |
| 2EH -- Set/Reset Verify Switch TRD413 2051
| |
| 2FH -- Get Disk Transfer Address (DTA) TRD413 2085
| |
| 30H -- Get DOS Version Number TRD413 2108
| |
| 31H -- Terminate Process and Remain Resident TRD413 2138
| |
| 33H -- Get/Set System Value TRD413 2175
| |
| 35H -- Get Interrupt Vector TRD413 2235
| |
| 36H -- Get Disk Free Space TRD413 2262
| |
| 38H -- Get or Set Country Dependent Information TRD413 2318
| |
| 39H -- Create Subdirectory (MKDIR) TRD413 2431
| |
| 3AH -- Remove Subdirectory (RMDIR) TRD413 2466
| |
| 3BH -- Change the Current Directory (CHDIR) TRD413 2498
| |
| 3CH -- Create a File (CREAT) TRD413 2530
| |
| 3DH -- Open a File TRD413 2577
| |
| 3EH -- Close a File Handle TRD413 2812
| |
| 3FH -- Read from a File or Device TRD413 2840
| |
| 40H -- Write to a File or Device TRD413 2886
| |
| 41H -- Delete a File from a Specified Directory (UNLINK) TRD413 2938
| |
| 42H -- Move File Read Write Pointer (LSEEK) TRD413 2971
| |
| 43H -- Change File Mode (CHMOD) TRD413 3035
| |
| 44H -- I/O Control for Devices TRD413 3092
| |
| 45H -- Duplicate a File Handle (DUP) TRD413 3103
| |
| 46H -- Force a Duplicate of a Handle (FORCDUP) TRD413 3137
| |
| 47H -- Get Current Directory TRD413 3170
| |
| 48H -- Allocate Memory TRD413 3202
| |
| 49H -- Free Allocated Memory TRD413 3237
| |
| 4AH -- Modify Allocated Memory Blocks (SETBLOCK) TRD413 3263
| |
| 4BH -- Load or Execute a Program (EXEC) TRD413 3303
| |
| 4CH -- Terminate a Process (EXIT) TRD413 3442
| |
| 4DH -- Get Return Code of a Subprocess (WAIT) TRD413 3466
| |
| 4EH -- Find First Matching File (FIND FIRST) TRD413 3494
| |
| 4FH -- Find Next Matching File (FIND NEXT) TRD413 3567
| |
| 54H -- Get Verify Setting TRD413 3606
| |
| 56H -- Rename a File TRD413 3628
| |
| 57H -- Get/Set File's Date and Time TRD413 3669
| |
| 59H -- Get Extended Error TRD413 3714
| |
| 5AH -- Create Unique File TRD413 3785
| |
| 5BH -- Create New File TRD413 3839
| |
| 5CH -- Lock/Unlock File Access TRD413 3878
| |
| 5E00H -- Get Machine Name TRD413 3972
| |
| 5E02H -- Set Printer Setup TRD413 4006
| |
| 5E03H -- Get Printer Setup TRD413 4051
| |
| 5F02H -- Get Redirection List Entry TRD413 4096
| |
| 5F03H -- Redirect Device TRD413 4169
| |
| 5F04H -- Cancel Redirection TRD413 4259
| |
| 62H -- Get Program Segment Prefix Address TRD413 4305
| |
| 65H -- Get Extended Country Information TRD413 4328
| |
| 66H -- Get/Set Global Code Page TRD413 4451
| |
| 67H -- Set Handle Count TRD413 4494
| |
| 68H -- Commit File TRD413 4539
| |
| 6CH -- Extended Open/Create TRD413 4562
| |
| APPENDIX C. I/O CONTROL FOR DEVICES (IOCTL) TRD414 4
| |
| 44H -- I/O Control for Devices (IOCtl) TRD414 50
| |
| APPENDIX D. EXPANDED MEMORY SUPPORT TRD415 3
| |
|
| |
|
| </PRE>
| | It consists of the following materials: |
| | * DOS Version 4.00 Technical Reference |
| | * DOS Version 4.00 Technical Quick Reference |
| | * Conditions of Use Statement |
| | * 3.5" (720KB) DOS Utilities Diskette |
| | * 5.25" (360KB) DOS Utilities Diskette |
|
| |
|
| ==Chapter 1== | | ==Contents== |
| <PRE>
| | # Introduction |
| CHAPTER 1. INTRODUCTION 7
| | # Accessing Disks |
| Organization of this Book 16
| | # Accessing Files With File Handles |
| New DOS 4.00 Services 43
| | # Accessing Files Using File Control Blocks |
| The Utilities Diskette 57
| | # Managing Device I/O |
| Minimum Hardware Configuration 79
| | # Controlling Processes |
|
| | # Creating OBJECT CODE LIBRARIES |
| CHAPTER 1. INTRODUCTION
| | # Creating an Executable File |
|
| | # Converting File Formats |
| This chapter provides information about this book, including the following:
| | # Debugging a Program |
|
| | :A. DOS 4.00 Interrupts |
| Organization of the book for quick information retrieval
| | :B. DOS 4.00 Function Calls |
| New and enhanced DOS 4.00 services
| | :C. I/O Control for Devices (IOCTL) |
| Contents of the utilities diskette
| | :D. Expanded Memory Support |
| Minimum hardware configuration.
| |
|
| |
| ORGANIZATION OF THIS BOOK
| |
|
| |
| This book is organized by logical application program development stages
| |
| necessary to develop an application program on DOS 4.00. You must:
| |
|
| |
| Write the source code for the program
| |
| Translate the source code to executable code
| |
| Load and execute the program
| |
| Debug the program
| |
| Create object code libraries (optional)
| |
| Convert your file formats (optional).
| |
|
| |
| In addition, the book tells how to make best use of the operating system by
| |
| writing your own device driver or by using the system extensions.
| |
|
| |
| Each chapter describes a particular subject. You do not need to read the
| |
| entire book to create programs or solve problems. Key topics also can be
| |
| found by referring to the index and the table of contents.
| |
|
| |
| The appendixes contain reference information for quick retrieval. They
| |
| contain the entire numerical list of DOS 4.00 services, including interrupts,
| |
| function calls, and device driver services.
| |
|
| |
| The Technical Quick Reference contains abbreviated information about
| |
| interrupts. Function calls are listed, along with input/output information
| |
| and error codes.
| |
|
| |
| NEW DOS 4.00 SERVICES
| |
|
| |
| DOS 4.00 replaces IBM DOS Version 3.30 and incorporates all services
| |
| previously provided by IBM DOS Version 3.30. Major new features include:
| |
|
| |
| Enhanced country support
| |
| Double-byte character support
| |
| A device driver
| |
| File system support of large disk media
| |
| Extended Memory Support (EMS)
| |
| Performance improvements to the file system.
| |
|
| |
| Several function requests within interrupt 21H have been enhanced.
| |
|
| |
| THE UTILITIES DISKETTE
| |
|
| |
| A utilities diskette is included with this book. It contains a listing of
| |
| the following utilities, and the description of each utility, to help
| |
| programmers develop an application program:
| |
|
| |
| DEBUG.COM A utility to isolate and determine errors in executable
| |
| programs.
| |
|
| |
| EXE2BIN.EXE A utility to convert executable file formats (.EXE) to
| |
| .COM formats to make them more compact and, therefore,
| |
| load more quickly.
| |
|
| |
| LIB.EXE A utility that allows the programmer to build and edit
| |
| object libraries.
| |
|
| |
| LINK.EXE A utility to translate object code to executable code.
| |
|
| |
| VDISK.ASM A fully documented programming example of a device
| |
| driver. However, this example does not reflect the
| |
| current level of VDISK.SYS.
| |
|
| |
| MINIMUM HARDWARE CONFIGURATION
| |
|
| |
| DOS 4.00 supports the following family of IBM Personal Computers and Personal
| |
| System/2 computers:
| |
|
| |
| The IBM Personal Computer
| |
| The IBM Personal Computer XT(TM)
| |
| The IBM Personal Computer XT(TM) Model 286(1)
| |
| The IBM Personal Computer AT(R) (all versions)(2)
| |
| The IBM PC Convertible
| |
| The IBM Personal System/2(R) Model 25 (all versions)
| |
| The IBM Personal System/2(R) Model 30 (all versions)
| |
| The IBM Personal System/2(R) Model 50 (all versions)
| |
| The IBM Personal System/2(R) Model 60 (all versions)
| |
| The IBM Personal System/2(R) Model 80 (all versions).
| |
|
| |
| NOTE: DOS 4.00 does not support the IBM PCjr.
| |
|
| |
| The minimum memory requirement is 256KB.
| |
|
| |
|
| |
| (1) Personal Computer XT is a trademark of the International Business
| |
| Machines Corporation.
| |
|
| |
| (2) Personal Computer AT and Personal System/2 are registered trademarks of
| |
| the International Business Machines Corporation.
| |
|
| |
| PART 1. WRITING PROGRAMS
| |
|
| |
| </PRE>
| |
| | |
| ==Chapter 8==
| |
| <PRE>
| |
| CHAPTER 8. CREATING AN EXECUTABLE FILE 35
| |
| The IBM Linker/2 40
| |
| Starting the LINK.EXE Program 56
| |
| Entering LINK Input at the Command Line 246
| |
| Using a Response File to Supply LINK Input 340
| |
| Using Linker Options 436
| |
| Preparing Files for CodeView /CODEVIEW 512
| |
| Reserving Paragraph Space /CPARMAXALLOC 530
| |
| Ordering Segments /DOSSEG 560
| |
| Controlling Data Loading /DSALLOCATE 583
| |
| Packing Executable Files /EXEPACK 607
| |
| Viewing the Options List /HELP 640
| |
| Controlling Run File Loading /HIGH 661
| |
| Displaying LINK-Time Information /INFORMATION 679
| |
| Copying Line Numbers to the Map File /LINENUMBERS 692
| |
| Producing a Public Symbol Map /MAP 731
| |
| Ignoring Default Libraries /NODEFAULTLIBRARYSEARCH 770
| |
| Preserving Compatibility /NOGROUPASSOCIATION 793
| |
| Preserving Lowercase /NOIGNORECASE 807
| |
| Setting the Overlay Interrupt /OVERLAYINTERRUPT 836
| |
| Pausing to Change Disks /PAUSE 856
| |
| Setting the Maximum Number of Segments /SEGMENTS 900
| |
| Setting the Stack Size /STACK 939
| |
| Reading the Map File 976
| |
| Creating an Overlaid Version of Your Program 1032
| |
| Specifying an Overlay Structure to LINK 1050
| |
| How LINK Formats the .EXE File 1075
| |
| Ordering Segments 1083
| |
| Segment Combine-Types 1106
| |
| Groups 1143
| |
| Instruction and Data Reference Errors 1159
| |
| Linker Error Messages 1215
| |
| Linker Limits 1681
| |
|
| |
| CHAPTER 8. CREATING AN EXECUTABLE FILE
| |
|
| |
| This chapter describes how to use the IBM Linker/2, which is LINK.EXE on your
| |
| utilities diskette, to produce executable programs.
| |
|
| |
| THE IBM LINKER/2
| |
|
| |
| The IBM Linker/2 combines object files with referenced library subroutines to
| |
| produce a file which can be relocated and executed. The object files you
| |
| supply to the linker for processing must be compiled or assembled source
| |
| files that are written in the programming languages supported by DOS 4.00.
| |
|
| |
| You can provide input to LINK by:
| |
|
| |
| Responding to a series of prompts
| |
| Entering input at the command line
| |
| Using a response file you have created.
| |
|
| |
| We recommend that you allow LINK to prompt you for responses until you are
| |
| comfortable with its parameters and operations.
| |
|
| |
| STARTING THE LINK.EXE PROGRAM
| |
|
| |
| To start the linker, type
| |
|
| |
| LINK
| |
|
| |
| at the command line and press Enter. The linker prompts you for information
| |
| by displaying the following prompts, one at a time:
| |
|
| |
| Object modules [.OBJ]:
| |
| Run file [filename.EXE]:
| |
| List file [NUL.MAP]:
| |
| Libraries [.LIB]:
| |
| Definitions File [NUL.DEF]:
| |
|
| |
| Each time the linker displays a prompt, it waits for your response before it
| |
| displays the next one. With the exception of the first prompt, you can
| |
| respond by pressing the Enter key. The linker supplies the default response
| |
| and takes you to the next prompt. At any prompt you can select the defaults
| |
| for all the remaining prompts by typing a semicolon (;) and pressing the
| |
| Enter key.
| |
|
| |
| You can also type in one or more linker options at any of the prompts. A
| |
| linker option instructs the linker to perform a special function as it
| |
| processes your object files. For example, specifying the /EXEPACK option
| |
| tells LINK to compress the .EXE file being created so it will load faster.
| |
| For descriptions of the options provided by LINK and guidelines for using
| |
| them, see "Using Linker Options" on page 8-8.
| |
|
| |
| Any error message generated by a response to a prompt will cause the linker
| |
| session to end. For a list of LINK error messages, see "Linker Error
| |
| Messages" on page 8-25. You can cause the linker session to end at any time
| |
| by simultaneously pressing the Ctrl and Break key so Control is then returned
| |
| to DOS 4.00.
| |
|
| |
| Object Modules Prompt
| |
|
| |
| After you enter LINK to start the linker, this prompt is displayed:
| |
|
| |
| Object Modules [.OBJ]:
| |
|
| |
| Here is where you enter the names of the object files to be used to create
| |
| your .EXE file. You must enter the name of at least one object file.
| |
| Separate each object filename from the next by a blank space or a plus sign
| |
| (+). If a plus sign is the last character on the line when Enter is pressed,
| |
| the Object Modules prompt reappears, allowing you to add more filenames.
| |
|
| |
| If you do not type an extension for a filename, LINK automatically supplies
| |
| the .OBJ extension.
| |
|
| |
| Include a drive and path with your file specification if the object file is
| |
| not on the current drive or in the current directory. If LINK cannot find an
| |
| object file, it does not display an error message until you have answered all
| |
| the prompts.
| |
|
| |
| When you have completed typing your input, press the Enter key.
| |
|
| |
| Run File Prompt
| |
|
| |
| The next prompt is displayed:
| |
|
| |
| Run File [filename.EXE]:
| |
|
| |
| Here is where you name the .EXE file that will be created. The filename
| |
| displayed in this prompt is the first one you typed next to the Object
| |
| Modules prompt. If you do not supply a new name and just press the Enter
| |
| key, this will be the name of your file. It will have an extension of .EXE.
| |
|
| |
| List File Prompt
| |
|
| |
| The next prompt is displayed:
| |
|
| |
| List File [NUL.MAP]:
| |
|
| |
| The linker list file is sometimes called the linker map. It contains the
| |
| names, load addresses, and lengths of all segments in a program. It also
| |
| lists the names and load addresses of any groups in the program, the
| |
| program's starting address, and messages generated by any errors the linker
| |
| may have encountered. For more information on map file contents, see
| |
| "Reading the Map File" on page 8-19.
| |
|
| |
| If you do not want a list file, do not type a filename. When you press the
| |
| Enter key, the file NUL.MAP is created, which means LINK will not save
| |
| mapping information.
| |
|
| |
| If you enter a filename without an extension, LINK supplies .MAP.
| |
|
| |
| By typing the /MAP option after your file specification, you tell LINK to
| |
| include a list of all public symbols and their addresses in the map file. If
| |
| you enter only /MAP without a filename, LINK creates a map file that includes
| |
| the public symbol information and has the same name as the first object file
| |
| you specified for the Object Modules prompt. Its extension will be .MAP.
| |
|
| |
| Libraries Prompt
| |
|
| |
| The next prompt is displayed:
| |
|
| |
| Libraries [.LIB]:
| |
|
| |
| List the names of the libraries you want linked and the names of any
| |
| directories you want searched for library names whose paths have not been
| |
| specified. Separate these specifications with a blank space or a plus sign
| |
| (+).
| |
|
| |
| When you supply directory specifications, LINK uses them to search for
| |
| default compiler libraries referred to in object files. If you do not supply
| |
| a filename extension for a library, LINK substitutes .LIB.
| |
|
| |
| The linker uses the environment variable LIB to search for libraries. Using
| |
| the SET command, you can assign the names of directories as well as complete
| |
| file specifications to LIB as search paths. If you have defined search paths
| |
| to the linker with LIB, this determines what information you need to enter.
| |
| For example, if you have included the search path to the directory that
| |
| contains your library in the value you set for LIB, you need enter only the
| |
| library name, not its path, at the prompt. If you have included the entire
| |
| file specification in the LIB definition, then this library will be searched
| |
| when references to public symbols are encountered. For a description of the
| |
| SET command, refer to the DOS 4.00 Command Reference.
| |
|
| |
| The maximum number of search paths you can enter at this prompt is limited to
| |
| 32. If your input is going to exceed a line, make the last character on the
| |
| line a plus sign (+) and press the Enter key. LINK then repeats the prompt
| |
| so you can continue to type.
| |
|
| |
| To locate the default libraries, LINK searches in the following order:
| |
|
| |
| 1. The current working directory
| |
| 2. The directories in the order listed following the LIBRARIES prompt
| |
| 3. The libraries specified by the LIB environment variable.
| |
|
| |
| LINK searches all the libraries until it finds the first definition of a
| |
| library public symbol.
| |
|
| |
| If you do not require any libraries to be searched for object code, press the
| |
| Enter key.
| |
|
| |
| Definition File Prompt
| |
|
| |
| This is the prompt displayed by LINK:
| |
|
| |
| Definition File [.DEF]:
| |
|
| |
| Since this IBM Linker/2 parameter for creating a module definition file is an
| |
| IBM Operating System/2 parameter that is not supported by DOS 4.00, press the
| |
| Enter key in response to this prompt.
| |
|
| |
| This completes your input to LINK, and LINK will now process the information
| |
| you have supplied. If no errors are encountered, LINK creates your
| |
| executable file.
| |
|
| |
| LINK uses available memory for the link session. If the files to be linked
| |
| create an output file that exceeds available memory, LINK creates a temporary
| |
| disk file to serve as storage. LINK creates the temporary file in the
| |
| current working directory. If you are working in a directory that is on a
| |
| diskette, LINK displays the following message:
| |
|
| |
| "Temporary file" name "has been created."
| |
|
| |
| "Do not change diskette in drive" letter:
| |
|
| |
| The name is a unique temporary filename created by the linker. After this
| |
| message appears, do not remove the diskette from the given drive (letter)
| |
| until the link session ends. If you remove the diskette, the operation of
| |
| LINK is unpredictable. If LINK unexpectedly ends, you may see the following
| |
| message:
| |
|
| |
| "Unexpected end of file on" name
| |
|
| |
| If you get this message, you must restart link from the beginning. After
| |
| LINK creates the executable file, it automatically deletes the temporary
| |
| file.
| |
|
| |
| An Example of a Prompts Session
| |
|
| |
| The following example links the object modules MODA.OBJ, MODB.OBJ, MODC.OBJ,
| |
| and STARTUP.OBJ. LINK searches the library file MATH.LIB in the \LIB
| |
| directory on drive B for routines and data used in the programs. LINK then
| |
| creates an executable file named MODA.EXE and a map file named ABC.MAP. The
| |
| /PAUSE option in the OBJECT MODULES prompt line causes LINK to pause while
| |
| you change diskettes. LINK then creates the executable file.
| |
|
| |
| LINK
| |
|
| |
| Object Modules [.OBJ]: moda + modb +
| |
| Object Modules [.OBJ]: modc + startup /PAUSE
| |
| Run File [MODA.EXE]:
| |
| List File [NUL.MAP]:abc
| |
| Libraries [.LIB]: b:\lib\math
| |
| Definitions File [NUL.DEF]:
| |
|
| |
| ENTERING LINK INPUT AT THE COMMAND LINE
| |
|
| |
| To run the linker from the command line, type the responses to LINK prompts
| |
| as parameters to the LINK command in the format that follows.
| |
|
| |
| With the exception of linker options, which begin with a forward slash (/)
| |
| and can appear anywhere on the command line, parameters specified to LINK
| |
| must be typed in the same order as the prompts are presented by LINK.
| |
| Separate parameters by commas, and if you omit a parameter within a sequence,
| |
| specify an additional comma.
| |
|
| |
| If you enter a partial command line that does not end in a semicolon, LINK
| |
| displays the prompts for the remaining parameters. You can enter values for
| |
| these prompts or just press the Enter key to accept the defaults.
| |
|
| |
| Refer to "Starting the LINK.EXE Program" on page 8-1 for default
| |
| descriptions.
| |
|
| |
| OBJLIST This parameter corresponds to the OBJECT FILES prompt. The
| |
| linker requires at least one object file. Separate file
| |
| specifications by a blank space or a plus sign (+). If your
| |
| input will exceed one line, type a plus sign as the last
| |
| character on the line before pressing Enter. The linker then
| |
| displays the OBJECT FILES prompt.
| |
|
| |
| ,RUNFILE This parameter corresponds to the RUN FILE prompt. If
| |
| specified, this is the name of the executable file created by
| |
| LINK.
| |
|
| |
| ,LISTFILE This parameter corresponds to the LIST FILE prompt. If
| |
| specified, this is the name of the map file.
| |
|
| |
| ,LIBRARYLIST This parameter corresponds to the LIBRARIES prompt. If
| |
| specified, this is the list of libraries LINK searches for
| |
| object code routines.
| |
|
| |
| ,DEFINITIONS FILE This parameter for creating module definition files
| |
| corresponds to the DEFINITIONS FILE prompt. Module definition
| |
| files are not supported by DOS 4.00.
| |
|
| |
| /OPTIONSLIST This parameter represents any linker options you wish to
| |
| specify. For the purpose of simplicity, the command format
| |
| shows this position for linker options. Actually, you can put
| |
| linker options anywhere on the command line. For a
| |
| description of linker options, see "Using Linker Options" on
| |
| page 8-8.
| |
|
| |
| ; The semicolon tells LINK you have completed your input. LINK
| |
| supplies the defaults for any remaining parameters.
| |
|
| |
| Examples of Command Line Input
| |
|
| |
| In the example below, an object module FILE.OBJ is processed to create the
| |
| executable file FILE.EXE. The linker searches the library ROUTINE.LIB for
| |
| routines and variables used within the program. It also creates a file
| |
| called FILE.MAP, which contains a list of the segments of the program and
| |
| groups. The following examples creates the file:
| |
|
| |
| LINK file.obj,file.exe,file.map,routine.lib;
| |
|
| |
| It is equal to the following line:
| |
|
| |
| LINK file , ,file, routine;
| |
|
| |
| In the following example, the linker loads and links the object modules
| |
| FUN.OBJ, TEXT.OBJ, TABLE.OBJ, and CARE.OBJ and searches for unresolved
| |
| references in the library file COBLIB.LIB. By default, the executable file
| |
| produced is named FUN.EXE. A list file named FUNLIST.MAP is also produced.
| |
|
| |
| LINK FUN+TEXT+TABLE+CARE,,FUNLIST,COBLIB.LIB /MAP;
| |
|
| |
| In the next example, LINK uses the two object modules STARTUP.OBJ and
| |
| FILE.OBJ on the current drive to create an executable file named FILE.EXE on
| |
| drive B:. LINK also creates a map file in the \MAP directory of the current
| |
| drive but does not search any libraries.
| |
|
| |
| LINK startup+file,b:file,\map\file;
| |
|
| |
| To link the application object file SAMPLE.OBJ using the the libraries
| |
| LIB1.LIB and LIB2.LIB, type:
| |
|
| |
| LINK sample,sample.exe, sample.map/M/LI, lib1+lib2/NOD;
| |
|
| |
| This command creates the file SAMPLE.EXE. It also creates the map file
| |
| SAMPLE.MAP. The command searches the library files LIB1.LIB and LIB2.LIB to
| |
| resolve any external references made in SAMPLE.OBJ. The /NOD option directs
| |
| LINK to ignore any default libraries specified in the object file.
| |
|
| |
| The linker uses default filename extensions if you do not explicitly provide
| |
| your own. In the example above, LINK extends the first occurrence of the
| |
| filename SAMPLE to SAMPLE.OBJ. LINK extends the library files with the .LIB
| |
| extension. The /LI option has LINK copy the line number information from the
| |
| object files.
| |
|
| |
| USING A RESPONSE FILE TO SUPPLY LINK INPUT
| |
|
| |
| To operate the linker with a response file, you must first create a file that
| |
| contains the responses you want LINK to process. You can give your file any
| |
| name you want. The responses you put in the file must be in the same order
| |
| as the LINK prompts:
| |
|
| |
| objectfiles
| |
| [runfile]
| |
|
| |
| [listfile]
| |
| [libraryfiles]
| |
| [definitionsfile]
| |
|
| |
| Each response to a prompt must begin on a separate line, but you can extend
| |
| long responses across more than one line by typing a plus sign as the last
| |
| character of each incomplete line. You can place one or more options on any
| |
| line.
| |
|
| |
| You can omit responses in your file and instead provide these responses with
| |
| a partial command line or have LINK prompt you for them.
| |
|
| |
| Once you have completed typing the responses, end the file with either a
| |
| semicolon or a carriage return and line feed combination. If you do not end
| |
| your file, LINK will display the last line of the file and wait for you to
| |
| press the Enter key.
| |
|
| |
| When you are ready to tell LINK to process the contents of your response
| |
| file, you must specify the file with a preceding AT sign (@), like this:
| |
|
| |
| LINK @C:\ABC\MYFILE.RSP
| |
|
| |
| This tells LINK the file specification is for a response file, and not a
| |
| response to a prompt. Remember to include a path with your file
| |
| specification when the file is not in the current directory.
| |
|
| |
| When you use the LINK command with a response file, LINK displays each prompt
| |
| on your screen with the corresponding response from your file. If the
| |
| response file does not contain responses for all the prompts, LINK displays
| |
| the appropriate prompts and waits for you to enter responses. When you type
| |
| an acceptable response, LINK continues the session.
| |
|
| |
| You can have LINK process only a part of your response file by placing a
| |
| semicolon on any line in the response file. When LINK reads the semicolon,
| |
| it supplies defaults for the remaining responses and ignores the rest of the
| |
| response file. For example, if you type a semicolon on the line of the
| |
| response file corresponding to the RUN FILE prompt, LINK uses the defaults
| |
| for the rest of the responses, starting with the executable file response.
| |
|
| |
| Examples of Response Files
| |
|
| |
| Suppose you enter these lines in a response file:
| |
|
| |
| FUN TEXT TABLE CARE
| |
| /PAUSE /MAP
| |
| FUNLIST
| |
| COBLIB.LIB;
| |
|
| |
| When the response file is processed, LINK loads the four object files named
| |
| FUN, TEXT, TABLE, and CARE. LINK produces two output files named FUN.EXE and
| |
| FUNLIST.MAP. The /PAUSE option causes LINK to pause before producing the
| |
| executable file (FUN.EXE). This permits you to change diskettes if
| |
| necessary. See the /PAUSE and /MAP options under "Using Linker Options" on
| |
| page 8-8 for more information.
| |
|
| |
| The response file below tells the linker to link the four object modules
| |
| MODA, MODB, MODC, and STARTUP. The linker pauses for you to change diskettes
| |
| before producing the runfile MODA.EXE. The linker also creates a map file
| |
| ABC.MAP and searches the library MATH.LIB in the \LIB directory of drive B:.
| |
|
| |
| moda modb modc startup /PAUSE
| |
|
| |
| abc
| |
| b:\lib\math
| |
|
| |
| The following example shows you how you can combine all three methods of
| |
| supplying file names. Assume that you have a response file called LIBRARY
| |
| that contains the following line:
| |
|
| |
| lib1+lib2+lib3+lib4;
| |
|
| |
| Now start LINK with a partial command line:
| |
|
| |
| LINK object1 object2
| |
|
| |
| LINK takes OBJECT1.OBJ and OBJECT2.OBJ as its object files, and asks for the
| |
| next line with the following:
| |
|
| |
| Run File [object1.EXE]: exec
| |
| List File [NUL.MAP]:
| |
| Libraries [.LIB]: @library
| |
|
| |
| Type EXEC so that the linker names the run file EXEC.EXE. Press the Enter
| |
| key to show that you do not want a map file, and type @ LIBRARY for the
| |
| linker to use in the response file containing the four library filenames.
| |
|
| |
| USING LINKER OPTIONS
| |
|
| |
| The table below lists LINK options and describes what they do.
| |
|
| |
| You can type linker options at any prompt or at any point on the command
| |
| line. You can specify an option's minimum abbreviation as shown in the
| |
| OPTIONS column, or as many characters of its long form as you like. The long
| |
| forms appear in parentheses. Remember to include the leading forward slash
| |
| (/) for each option you specify.
| |
|
| |
| A complete format description, usage guidelines, and examples for each option
| |
| follow this table.
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | OPTION TASK DESCRIPTION |
| |
| +---------------------------------------------------------------------------+
| |
| | /CO Prepare the .EXE file for later symbolic debugging (/CODEVIEW). |
| |
| | You should not use this option with the /EXEPACK option. |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | OPTION TASK DESCRIPTION |
| |
| +---------------------------------------------------------------------------+
| |
| | /CP Reduce the maximum amount of paragraphs reserved for your |
| |
| | program from the default of 64KB minus 1 to whatever you specify |
| |
| | (/CPARMAXALLOC). |
| |
| +---------------------------------------------------------------------------+
| |
| | /DO Force the ordering of segments (/DOSSEG). |
| |
| +---------------------------------------------------------------------------+
| |
| | /DS Load data starting at the high end of the segment (/DSALLOCATE). |
| |
| | This option is used with the /HIGH option. |
| |
| +---------------------------------------------------------------------------+
| |
| | /E Compress the .EXE file for faster loading (/EXEPACK). You |
| |
| | should not use this option with the /CODEVIEW option. |
| |
| +---------------------------------------------------------------------------+
| |
| | /HE Display a list of the LINK options on your screen (/HELP). |
| |
| +---------------------------------------------------------------------------+
| |
| | /HI Cause the .EXE file to be placed in the highest storage |
| |
| | available when loaded (/HIGH). This option is used with the |
| |
| | /DSALLOCATE option. |
| |
| +---------------------------------------------------------------------------+
| |
| | /I Display LINK processing messages (/INFORMATION). |
| |
| +---------------------------------------------------------------------------+
| |
| | /LI Add a list of the starting addresses of program source lines to |
| |
| | your map file (/LINENUMBERS). If you do not specify a map file, |
| |
| | this option causes one to be created. |
| |
| +---------------------------------------------------------------------------+
| |
| | /M Add a list of public symbols declared by your object files to |
| |
| | your map file (/MAP). If you do not specify a map file, this |
| |
| | option causes one to be created. |
| |
| +---------------------------------------------------------------------------+
| |
| | /NOD Ignore any default compiler library names found in an object |
| |
| | file (/NODEFAULTLIBRARYSEARCH). This allows you to supply your |
| |
| | own library names. |
| |
| +---------------------------------------------------------------------------+
| |
| | /NOG Provide compatibility with previous compiler versions |
| |
| | (/NOGROUPASSOCIATION). |
| |
| +---------------------------------------------------------------------------+
| |
| | NOI Distinguish between uppercase and lowercase characters |
| |
| | (/NOIGNORECASE). This option is for files created by compilers |
| |
| | that make this distinction. |
| |
| +---------------------------------------------------------------------------+
| |
| | /O Set the interrupt number to other than 3FH for passing control |
| |
| | to overlays (/OVERLAYINTERRUPT). |
| |
| +---------------------------------------------------------------------------+
| |
| | /PAU Pause before generating the .EXE file (/PAUSE). This option |
| |
| | allows you to insert a diskette. |
| |
| +---------------------------------------------------------------------------+
| |
| | /SE Set the maximum number of logical segments to a value other than |
| |
| | the the default of 128 (/SEGMENT). |
| |
| +---------------------------------------------------------------------------+
| |
| | /ST Set the stack size to other than the size calculated by LINK |
| |
| | (/STACK). |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| PREPARING FILES FOR CODEVIEW
| |
| /CODEVIEW
| |
|
| |
| This option directs LINK to include symbolic debugging information for
| |
| CodeView in the output .EXE file for IBM languages that support the CodeView
| |
| debugger.
| |
|
| |
| FORMAT
| |
|
| |
| /CODEVIEW
| |
|
| |
| The minimum abbreviation is /CO.
| |
|
| |
| COMMENTS
| |
|
| |
| WARNING: IF /CODEVIEW IS USED WITH THE /EXEPACK OPTION, ALL SYMBOLIC
| |
| DEBUGGING INFORMATION WILL BE LOST.
| |
|
| |
| RESERVING PARAGRAPH SPACE
| |
| /CPARMAXALLOC
| |
|
| |
| This option allows you to change the default value of the MAXALLOC field,
| |
| which controls the maximum number of paragraphs reserved in storage for your
| |
| program. A paragraph is defined as the smallest storage unit (16 bytes)
| |
| addressable by a segment register.
| |
|
| |
| FORMAT
| |
|
| |
| /CPARMAXALLOC:number
| |
|
| |
| The minimum abbreviation is /CP.
| |
|
| |
| COMMENTS
| |
|
| |
| The maximum number of paragraphs reserved for a program is determined by the
| |
| value of the MAXALLOC field at offset 0CH in the EXE header.
| |
|
| |
| The default for the MAXALLOC field is 65535 (decimal), or 64KB minus 1. You
| |
| can reset the default to any number between 1 and 65535 (decimal, octal, or
| |
| hexadecimal). Reducing the number is helpful because:
| |
|
| |
| Program efficiency is not increased by reserving all available memory.
| |
| You may need to run another program within your program and you need to
| |
| reserve space for the run program.
| |
|
| |
| If the value you specify is less than the computed value of MINALLOC (at
| |
| offset 0AH), the linker uses the value of MINALLOC instead.
| |
|
| |
| ORDERING SEGMENTS
| |
| /DOSSEG
| |
|
| |
| This option forces segments to be ordered according to the following rules:
| |
|
| |
| 1. All segments with a class name ending in CODE
| |
|
| |
| 2. All other segments outside of DGROUP
| |
|
| |
| 3. DGROUP segments in the following order:
| |
|
| |
| a. Any segments of class BEGDATA. (This class name is reserved for IBM
| |
| use.)
| |
| b. Any segments not of class BEGDATA, BSS, or STACK.
| |
| c. Segments of class BSS.
| |
| d. Segments of class STACK.
| |
|
| |
| FORMAT
| |
|
| |
| /DOSSEG
| |
|
| |
| The minimum abbreviation is /DO.
| |
|
| |
| CONTROLLING DATA LOADING
| |
| /DSALLOCATE
| |
|
| |
| By default, LINK loads all data starting at the low end of the data segment.
| |
| At run time, LINK sets the DS (data segment) pointer to the lowest possible
| |
| address to allow the entire data segment to be used.
| |
|
| |
| You can use the /DSALLOCATE option to tell LINK to load all data starting at
| |
| the high end of the data segment. To do this, at run time, set the DS
| |
| pointer to the lowest data segment address that contains program data.
| |
|
| |
| FORMAT
| |
|
| |
| /DSALLOCATE
| |
|
| |
| The minimum abbreviation is /DS.
| |
|
| |
| COMMENTS
| |
|
| |
| This option is typically used with the /HIGH option to take advantage of
| |
| unused storage within the data segment. You can reserve any available
| |
| storage below the area specifically reserved for DGROUP, using the same DS
| |
| pointer.
| |
|
| |
| PACKING EXECUTABLE FILES
| |
| /EXEPACK
| |
|
| |
| This option directs LINK to remove sequences of repeated bytes (typically
| |
| nulls) and to optimize the load-time relocation table before creating the DOS
| |
| 4.00 executable file.
| |
|
| |
| FORMAT
| |
|
| |
| /EXEPACK
| |
|
| |
| The minimum abbreviation is /E.
| |
|
| |
| COMMENTS
| |
|
| |
| Executable files linked with this option are usually smaller and load faster
| |
| than files linked without this option. However, you cannot use symbolic
| |
| debugging programs with packed files.
| |
|
| |
| This option does not always save a significant amount of disk space and
| |
| sometimes actually may increase file size. Programs that have a large number
| |
| of load-time relocations (about 500 or more) or long streams of repeated
| |
| characters are usually shorter if packed.
| |
|
| |
| WARNING: IF THE /CODEVIEW OPTION IS USED WITH /EXEPACK, ALL SYMBOLIC
| |
| DEBUGGING INFORMATION WILL BE LOST.
| |
|
| |
| EXAMPLE
| |
|
| |
| This example creates a packed version of file PROGRAM.EXE.
| |
|
| |
| LINK program /E;
| |
|
| |
| VIEWING THE OPTIONS LIST
| |
| /HELP
| |
|
| |
| This option causes LINK to write a list of the available options to the
| |
| screen. This may be convenient if you need a reminder of the available
| |
| options. Do not give a filename when using the /HELP option.
| |
|
| |
| FORMAT
| |
|
| |
| /HELP
| |
|
| |
| The minimum abbreviation is /HE.
| |
|
| |
| EXAMPLE
| |
|
| |
| LINK /HELP
| |
|
| |
| NOTE: Many LINK options that are used only with IBM Operating
| |
| System/2(TM)(1) are displayed when using the /HELP option. These
| |
| options cannot be used when creating programs to run on DOS 4.00.
| |
|
| |
| CONTROLLING RUN FILE LOADING
| |
| /HIGH
| |
|
| |
| You can place the run file as low or as high in storage as possible. Using
| |
| the /HIGH option directs LINK to cause the loader to place the run file as
| |
| high as possible in storage without overlaying the transient portion of
| |
| COMMAND.COM. The COMMAND.COM file occupies the highest area of storage when
| |
| loaded. Without the /HIGH option, the loader places the run file as low as
| |
| possible in storage.
| |
|
| |
| Use the /HIGH option in association with the /DSALLOCATE option.
| |
|
| |
| FORMAT
| |
|
| |
| /HIGH
| |
|
| |
| The minimum abbreviation is /HI.
| |
|
| |
| DISPLAYING LINK-TIME INFORMATION
| |
| /INFORMATION
| |
|
| |
| This option causes the linker to display the phase of processing it is
| |
| running, and the name of each input module as it is linked. This is useful
| |
| during debugging.
| |
|
| |
| FORMAT
| |
|
| |
| /INFORMATION
| |
|
| |
| The minimum abbreviation is /I.
| |
|
| |
| COPYING LINE NUMBERS TO THE MAP FILE
| |
| /LINENUMBERS
| |
|
| |
| This option directs the linker to copy the starting address of each program
| |
| source line to a map file. The starting address is the address of the first
| |
| instruction that corresponds to the source line.
| |
|
| |
|
| |
| (1) Operating System/2 is a trademark of the International Business Machines
| |
| Corporation.
| |
|
| |
| FORMAT
| |
|
| |
| /LINENUMBERS
| |
|
| |
| The minimum abbreviation is /LI.
| |
|
| |
| COMMENTS
| |
|
| |
| LINK copies the line number data only if you give a map filename in the LINK
| |
| command line, and only if the given object file has line number information.
| |
| Line numbering is available in some high-level languages.
| |
|
| |
| If an object file has no line number information, the linker ignores the
| |
| /LINENUMBERS option.
| |
|
| |
| NOTE: If you do not specify a map file in a LINK command, you can still use
| |
| the /LINENUMBERS option to force the linker to create a map file.
| |
| Place the option at or before the LIST FILE prompt. LINK gives the
| |
| forced map file the same filename as the first object file specified
| |
| in the command and gives it the default extension .MAP.
| |
|
| |
| EXAMPLE
| |
|
| |
| This example causes the line number information in the object file FILE.OBJ
| |
| to be copied to the map file FILE.MAP.
| |
|
| |
| LINK file/LINENUMBERS,,file,mylib;
| |
|
| |
| PRODUCING A PUBLIC SYMBOL MAP
| |
| /MAP
| |
|
| |
| This option causes LINK to produce a listing of all public symbols declared
| |
| in your program. This list is copied to the map file created by the linker.
| |
|
| |
| FORMAT
| |
|
| |
| /MAP:number
| |
|
| |
| The minimum abbreviation is /M.
| |
|
| |
| For a complete description of the listing file format, see "Reading the Map
| |
| File" on page 8-19.
| |
|
| |
| COMMENTS
| |
|
| |
| The number parameter specifies the maximum number of public symbols that the
| |
| linker can sort in the map file. The limit is 32768, and the default is 2048
| |
| if no number is specified. If the limit is exceeded, the linker produces an
| |
| un-sorted list and issues the following warning:
| |
|
| |
| MAP SYMBOL LIMIT TOO HIGH
| |
|
| |
| If you get this error, link again with a lower number. The limit varies
| |
| according to how many segments the program has and how much memory is
| |
| available.
| |
|
| |
| Specifying a number also causes the public symbols to be sorted by address
| |
| only, not by name, regardless of the number. To reduce the size of your map
| |
| files by removing the list sorted by name, link with /MAP followed by the
| |
| lowest possible number that will accommodate the number of public symbols in
| |
| your program.
| |
|
| |
| NOTE: If you do not specify a map file in a LINK command, you can use the
| |
| /MAP option to force the linker to create a map file. LINK gives the
| |
| forced map file the same name as the first object file specified in
| |
| the command and the default extension .MAP.
| |
|
| |
| IGNORING DEFAULT LIBRARIES
| |
| /NODEFAULTLIBRARYSEARCH
| |
|
| |
| This option directs the linker to ignore any library names it may find in an
| |
| object file. A high-level language compiler may add a library name to an
| |
| object file to ensure that a default set of libraries is linked with the
| |
| program. Using this option bypasses these default libraries and lets you
| |
| name the libraries you want by including them on the LINK command line.
| |
|
| |
| FORMAT
| |
|
| |
| /NODEFAULTLIBRARYSEARCH
| |
|
| |
| The minimum abbreviation is /NOD.
| |
|
| |
| EXAMPLE
| |
|
| |
| This example links the object files STARTUP.OBJ and FILE.OBJ with routines
| |
| from the libraries EM, SLIBFP, and SLIBC. Any default libraries that may
| |
| have been named in STARTUP.OBJ or FILE.OBJ are ignored.
| |
|
| |
| LINK startup+file/NOD,,,em+slibfp+slibc;
| |
|
| |
| PRESERVING COMPATIBILITY
| |
| /NOGROUPASSOCIATION
| |
|
| |
| This option causes the linker to process a certain class of fix-up routines
| |
| in a manner compatible with previous versions of the linker. This option is
| |
| provided primarily for compatibility with previous versions of other IBM
| |
| language compilers.
| |
|
| |
| FORMAT
| |
|
| |
| /NOGROUPASSOCIATION
| |
|
| |
| The minimum abbreviation is /NOG.
| |
|
| |
| PRESERVING LOWERCASE
| |
| /NOIGNORECASE
| |
|
| |
| This option directs LINK to treat uppercase and lowercase letters in symbol
| |
| names as distinct letters. Normally, LINK considers uppercase and lowercase
| |
| letters to be identical, treating the names TWO, Two, and two as the same.
| |
| When you use the /NOIGNORECASE option, the linker treats TWO, Two, and two as
| |
| different names.
| |
|
| |
| FORMAT
| |
|
| |
| /NOIGNORECASE
| |
|
| |
| The minimum abbreviation is /NOI.
| |
|
| |
| COMMENTS
| |
|
| |
| This option is typically used with object files created by high-level
| |
| language compilers. Some compilers treat uppercase and lowercase letters as
| |
| distinct letters and assume that the linker does the same.
| |
|
| |
| EXAMPLE
| |
|
| |
| This command causes the linker to treat uppercase and lowercase letters in
| |
| symbol names as distinct letters. The object file FILE.OBJ is linked with
| |
| routines from the library \SLIBC.LIB located in the \LIB directory.
| |
|
| |
| LINK file/NOI,,,\lib\slibc;
| |
|
| |
| SETTING THE OVERLAY INTERRUPT
| |
| /OVERLAYINTERRUPT
| |
|
| |
| By default, the DOS 4.00 interrupt number used for passing control to
| |
| overlays is 3FH. This option allows you to select a different interrupt
| |
| number.
| |
|
| |
| FORMAT
| |
|
| |
| /OVERLAYINTERRUPT:number
| |
|
| |
| The minimum abbreviation is /O.
| |
|
| |
| COMMENTS
| |
|
| |
| The number can be a decimal number from 0 through 255, an octal number from 0
| |
| through 0377, or a hexadecimal number from 0 to FFH. Numbers that conflict
| |
| with DOS 4.00 interrupts are not prohibited, but IBM does not recommend their
| |
| use.
| |
|
| |
| PAUSING TO CHANGE DISKS
| |
| /PAUSE
| |
|
| |
| This option causes LINK to pause so that you can change disks before writing
| |
| the executable file to disk.
| |
|
| |
| FORMAT
| |
|
| |
| /PAUSE
| |
|
| |
| The minimum abbreviation is /PAU.
| |
|
| |
| COMMENTS
| |
|
| |
| If you choose the /PAUSE option, the linker displays the following message
| |
| before creating the run file:
| |
|
| |
| ABOUT TO GENERATE .EXE FILE
| |
| CHANGE DISKETTE IN DRIVE letter AND PRESS <ENTER>
| |
|
| |
| The letter is the proper drive name. This message appears after the linker
| |
| has read data from the object and library files, and after writing data to
| |
| the map file, if one was specified. LINK resumes processing when you press
| |
| the Enter key. After LINK writes the executable file to disk, the following
| |
| message appears:
| |
|
| |
| PLEASE REPLACE ORIGINAL DISKETTE
| |
| IN DRIVE letter AND PRESS <ENTER>
| |
|
| |
| NOTE: Do not remove the disk used for the temporary file, if one has been
| |
| created. If the temporary disk message appears when you have
| |
| specified the /PAUSE option, you should simultaneously press the Ctrl
| |
| and C keys to end the LINK session. Rearrange your files so that LINK
| |
| can write the temporary file and the executable file to the same disk,
| |
| then try again.
| |
|
| |
| EXAMPLE
| |
|
| |
| This command causes the linker to pause just before creating the executable
| |
| file file.exe. After creating the executable file, LINK pauses again to let
| |
| you replace the original disk.
| |
|
| |
| LINK file/PAUSE,file,,\lib\math;
| |
|
| |
| SETTING THE MAXIMUM NUMBER OF SEGMENTS
| |
| /SEGMENTS
| |
|
| |
| This option directs the linker to process no more than number + 3 logical
| |
| segments per program. If it meets more than this limit, the linker displays
| |
| an error message and stops linking. The /SEGMENTS option bypasses the
| |
| default limit of 128 logical segments.
| |
|
| |
| FORMAT
| |
|
| |
| /SEGMENTS:number
| |
|
| |
| The minimum abbreviation is /SE.
| |
|
| |
| COMMENTS
| |
|
| |
| If you do not specify /SEGMENTS, the linker reserves enough storage space to
| |
| process up to 128 logical segments. If your program has more than 128
| |
| logical segments, you must set the segment limit higher to increase the
| |
| number of logical segments LINK can process. Set the segment limit lower if
| |
| you get the following LINK error message:
| |
|
| |
| REQUESTED SEGMENT LIMIT TOO HIGH
| |
|
| |
| The number can be any integer value in the range 1 to 3072. It must be a
| |
| decimal, octal, or hexadecimal number. Octal numbers must have a leading
| |
| zero. Hexadecimal numbers must start with a leading zero followed by a
| |
| lowercase x; for example, 0x4B.
| |
|
| |
| EXAMPLE
| |
|
| |
| This example sets the logical segment limit to 192:
| |
|
| |
| LINK file/SE:192;
| |
|
| |
| The following example sets the logical segment limit to 255 (X'FF'):
| |
|
| |
| LINK moda+modb,run/SEGMENTS:0xff,ab,em+mlibfp;
| |
|
| |
| SETTING THE STACK SIZE
| |
| /STACK
| |
|
| |
| This option sets the program stack to the number of bytes given by size. The
| |
| linker automatically calculates the stack size of a program, basing the size
| |
| on the size of any stack segments given in the object files. If you specify
| |
| /STACK, the linker uses the given size in place of any value it may have
| |
| calculated.
| |
|
| |
| FORMAT
| |
|
| |
| /STACK:size
| |
|
| |
| The minimum abbreviation is /ST.
| |
|
| |
| COMMENTS
| |
|
| |
| The size can be any positive integer value in the range 1 through 65534. The
| |
| value can be a decimal, octal, or hexadecimal number. Octal numbers must
| |
| begin with a zero. Hexadecimal numbers must begin with a leading zero
| |
| followed by a lowercase x; for example, 0x1B.
| |
|
| |
| The stack size can also be changed after linking with the EXEMOD utility.
| |
|
| |
| EXAMPLES
| |
|
| |
| This example sets the stack size to 512 bytes:
| |
|
| |
| LINK file/STACK:512;
| |
|
| |
| The following example sets the stack size to 255 (X'FF') bytes:
| |
|
| |
| LINK moda+modb,run/ST:0xFF,ab.\lib\start;
| |
|
| |
| The following example sets the stack size to 24 (30 octal) bytes:
| |
|
| |
| LINK startup+file/ST:030;
| |
|
| |
| READING THE MAP FILE
| |
|
| |
| The map file lists the names, load addresses, and lengths of all segments in
| |
| a program. It also lists the names and load addresses of any groups in the
| |
| program, the program's start address, and messages about any errors the
| |
| linker may have encountered. If you use the /MAP LINK option, the map file
| |
| lists the names and load addresses of all public symbols.
| |
|
| |
| In the map file, segment information has the general form:
| |
|
| |
| Start Stop Length Name Class
| |
|
| |
| 00000H 02B86H 02B87H _TEXT CODE
| |
| 02B90H 05091H 02502H EMULATOR_TEXT CODE
| |
| 05092H 05092H 00000H C_ETEXT ENDCODE
| |
| 050A0H 0520FH 00170H EMULATOR_DATA FAR_DATA
| |
| 05210H 05245H 00036H NULL BEGDATA
| |
| 05246H 05761H 0051CH _DATA DATA
| |
|
| |
| The Start column shows the address of the first byte in the segment. The
| |
| number shown is the offset from the beginning of the program. This number is
| |
| referred to as the frame number. The Stop column shows the address of the
| |
| last byte in the segment. The Length is the length of the segment in bytes.
| |
| The Name column shows the name of the segment and the Class column shows the
| |
| class name of the segment.
| |
|
| |
| Group information has the general form:
| |
|
| |
| Origin Group
| |
|
| |
| 0521:0 DGROUP
| |
|
| |
| Program entry point at 0000:02A0
| |
|
| |
| If you have specified the /MAP LINK option, the linker adds a public symbol
| |
| list to the map file. Symbols are listed twice: first in alphabetical order,
| |
| then in the order of their load addresses. This list has the general form
| |
| shown in the following example. (For each symbol address, the number to the
| |
| left of the colon represents a frame number.)
| |
|
| |
| Address Publics by Name
| |
|
| |
| 0003:071A $i8_implicit_exp
| |
| 0003:0718 $i8_inpbas
| |
| 0001:287C $i8_input
| |
| 0003:0719 $i8_input_ws
| |
| 0001:0CF6 $i8_output
| |
|
| |
| Address Publics by Value
| |
|
| |
| 0001:0010 _main
| |
| 0001:01B0 _countwords
| |
| 0001:0238 _analyze
| |
| 0001:02A0 __astart
| |
| 0001:0368 __cintDIV
| |
|
| |
| CREATING AN OVERLAID VERSION OF YOUR PROGRAM
| |
|
| |
| You can direct LINK to create an overlaid version of your program. This
| |
| means that the COMMAND.COM loader will load parts of your program only when
| |
| they are needed, and these parts will share the same space in storage. Your
| |
| overlaid program should run in less storage, but probably it will run more
| |
| slowly because time is needed to read and load the code into storage.
| |
|
| |
| The use of overlays is restricted to object modules built with IBM high-level
| |
| languages that support overlays. Refer to the language manuals that came
| |
| with your compiler for a description of overlays.
| |
|
| |
| Control is passed to overlay modules by a standard 8086-long (32-bit) | |
| CALL/RETURN instruction. You cannot use long jumps or indirect calls
| |
| (through a function pointer) to pass control to an overlay. When a pointer
| |
| calls a function, the called function must be either in the same overlay or
| |
| in the root.
| |
|
| |
| SPECIFYING AN OVERLAY STRUCTURE TO LINK
| |
|
| |
| You specify the overlay structure to the linker in response to the OBJECT
| |
| MODULES prompt. Loading is automatic. You specify the overlays in the list
| |
| of modules that you submit to the linker by enclosing them in parentheses.
| |
| Each parenthetical list represents one overlay. For example:
| |
|
| |
| Object Modules [.OBJ] : a+(b+c)+(e+f)+g+(i)
| |
|
| |
| The elements (b+c), (e+f), and (i) are overlays. The remaining modules, and
| |
| any drawn from the run time libraries, make up the resident or root part of
| |
| your program. LINK loads your program or root overlays into the same region
| |
| of storage, so only one can be resident at a time. LINK does not allow
| |
| duplicate names in different overlays, so each module can occur only once in
| |
| a program.
| |
|
| |
| The linker replaces calls from the root to an overlay and calls from an
| |
| overlay to another overlay with an interrupt, followed by the module
| |
| identifier and offset. The DOS interrupt number used by LINK is 3FH. You
| |
| can change this interrupt number by specifying the /OVERLAYINTERRUPT option.
| |
| See "Using Linker Options" on page 8-8 for more information.
| |
|
| |
| LINK adds the name for the overlays to the .EXE file, and encodes the name of
| |
| this file into the program so the overlay manager can get access to it.
| |
|
| |
| HOW LINK FORMATS THE .EXE FILE
| |
|
| |
| This section is provided if you need to know how LINK uses IBM Macro
| |
| Assembler/2(TM) pseudo-up instructions to determine the format of the .EXE
| |
| file. Unlike high-level language compilers such as IBM C/2 Compiler(TM),(2)
| |
| the IBM Macro Assembler does not check to determine if the 64KB physical
| |
| segment limit of DOS 4.00 has been exceeded.
| |
|
| |
| ORDERING SEGMENTS
| |
|
| |
| LINK copies segments to the executable file in the same order that it meets
| |
| them in the object files. This order is maintained throughout the program
| |
| unless the linker finds two or more segments having the same class, as
| |
| defined by the SEGMENT pseudo-op instruction. Segments having identical
| |
| classes are copied to the executable files as contiguous blocks. The linker
| |
| uses a segment's align-type defined in the SEGMENT pseudo-op instruction to
| |
| set the starting address for the segment. The align types are BYTE, WORD,
| |
| PARA, and PAGE. These correspond to starting addresses at byte, word,
| |
| paragraph, and page boundaries, representing addresses that are multiples of
| |
| 1, 2, 16, and 256, respectively. The default align-type is PARA.
| |
|
| |
| When the linker encounters a segment, it checks the align-type before copying
| |
| the segment to the executable file. If the align-type is WORD, PARA, or
| |
| PAGE, the linker checks the executable image to see if the last byte copied
| |
| ends at an appropriate boundary. If not, LINK adds extra null bytes to the
| |
| image.
| |
|
| |
|
| |
| (2) Macro Assembler/2 and C/2 Compiler are trademarks of the International
| |
| Business Machines Corporation.
| |
|
| |
| SEGMENT COMBINE-TYPES
| |
|
| |
| LINK uses combine-types that are defined in SEGMENT pseudo-op instructions to
| |
| determine whether two or more segments sharing the same segment name should
| |
| be one segment. The combine-types are PUBLIC, STACK, COMMON, and PRIVATE.
| |
|
| |
| If a segment is combine-type PUBLIC, the linker combines it with any
| |
| segments of the same name and class. When LINK combines segments, it
| |
| makes the segments contiguous in storage; you can reach each address in
| |
| the segments using an offset from one frame address. The result is the
| |
| same as if the segments were defined as a whole in the source file.
| |
|
| |
| The linker preserves the align-type defined in the SEGMENT pseudo-op
| |
| instruction for each code and data segment it adds to the combined
| |
| segment.
| |
|
| |
| If a segment is combine-type STACK, the linker combines individual
| |
| segments as it does for PUBLIC combine-types. For STACK segments, LINK
| |
| copies an initial stack-pointer value to the executable file. This
| |
| stack-pointer value is the offset to the end of the first STACK segment
| |
| (or combined STACK segment) that LINK meets. If you use the STACK type
| |
| for STACK segments, you need not give instructions to load the segment | |
| into the SS register.
| |
|
| |
| If a segment is combine-type COMMON, the linker combines it with any
| |
| segments of the same name and class. When LINK combines COMMON segments,
| |
| it places the start of each segment at the same address. This creates a
| |
| series of overlapping segments. The resulting combination segment has a
| |
| length equal to the longest individual segment.
| |
|
| |
| LINK assigns a default combine-type of PRIVATE to any segments with no
| |
| explicit combine-type definition in the source file. LINK does not
| |
| combine PRIVATE segments.
| |
|
| |
| If LINK tries to combine segments that total more than 64KB, it displays an
| |
| error message.
| |
|
| |
| GROUPS
| |
|
| |
| The GROUP pseudo-op instruction gives addressability to non-contiguous
| |
| segments of various classes relative to the same frame address. When LINK
| |
| encounters a GROUP instruction, it adjusts all storage references to items in
| |
| the group to the same frame address.
| |
|
| |
| Segments of a group need not be contiguous, belong to one class, or have the
| |
| same combine-type. However, all segments specified by the GROUP must fit
| |
| within 64KB of storage. If the group is smaller than 64KB of storage, LINK
| |
| may place segments that are not part of the group in the same storage area.
| |
|
| |
| LINK does not specifically check that all segments in a group fit within 64KB
| |
| of storage. If the segments are larger than the 64KB maximum, the linker can
| |
| produce a FIX-UP OVERFLOW error.
| |
|
| |
| INSTRUCTION AND DATA REFERENCE ERRORS
| |
|
| |
| Once the linker knows the starting address of each segment in a program and
| |
| establishes all segment combinations and groups, it attempts to fix up any
| |
| unresolved references to labels and variables. The linker computes an
| |
| appropriate offset and segment address and replaces the temporary address
| |
| values with the new values.
| |
|
| |
| The size of the value that LINK computes depends on the type of reference.
| |
| If LINK discovers an error in the anticipated size of the reference, it
| |
| displays a fixup overflow error message. This happens, for example, when a
| |
| program tries to use a 16-bit offset to address an instruction in a segment
| |
| that has a different frame address. It also occurs when the segments in a
| |
| group do not fit within a single, 64K block of storage.
| |
|
| |
| LINK resolves four types of references:
| |
|
| |
| Short
| |
|
| |
| Near self-relative
| |
|
| |
| Near segment-relative
| |
|
| |
| Long.
| |
|
| |
| - A SHORT reference occurs in JMP instructions that try to pass control
| |
| to labeled instructions in the same segment or group. The target
| |
| instruction must be no longer than 128 bytes from the point of
| |
| reference. The linker computes a signed, 8-bit number for this SHORT
| |
| reference. It displays an error message if the target instruction
| |
| belongs to a different segment or group (different frame address).
| |
| The linker also displays an error message if the distance from the
| |
| frame address to the target is more than 128 bytes in either
| |
| direction.
| |
|
| |
| - A NEAR SELF-RELATIVE reference occurs in instructions which access
| |
| data relative to the same segment or group. The linker computes a
| |
| 16-bit offset for this NEAR SELF-RELATIVE reference. It displays an
| |
| error message if the data resides in more than one segment or group.
| |
|
| |
| - A NEAR SEGMENT-RELATIVE reference occurs in instructions that attempt
| |
| to access data either in a specified segment or group or relative to
| |
| a specified segment register. LINK computes a 16-bit offset for this
| |
| NEAR SEGMENT-RELATIVE reference. It displays an error message if the
| |
| offset of the target within the specified frame is greater than 64KB
| |
| or less than 0 bytes. LINK also displays an error message if LINK
| |
| cannot address the beginning of the (canonical) frame of the target.
| |
|
| |
| - A LONG reference occurs in CALL instructions that try to get access
| |
| to an instruction in another segment or group. LINK computes a
| |
| 16-bit frame address and a 16-bit offset for this LONG reference.
| |
| The linker displays an error message if the computed offset is
| |
| greater than 64K or less than 0 bytes. The linker also displays an
| |
| error message if LINK cannot address the beginning of the (canonical)
| |
| frame of the target.
| |
|
| |
| LINKER ERROR MESSAGES
| |
|
| |
| This section lists error messages produced by the IBM Linker.
| |
|
| |
| Fatal errors cause the linker to stop running. Fatal error messages have the
| |
| following format:
| |
|
| |
| location: FATAL ERROR L1xxx: message text
| |
|
| |
| Non-fatal errors indicate problems in the executable file. LINK produces the
| |
| executable file (and sets the error bit in the header if for protected mode).
| |
| Non-fatal error messages have the following format:
| |
|
| |
| location: ERROR L2 xxx: message text
| |
|
| |
| Warnings indicate possible problems in the executable file. LINK produces
| |
| the executable file (it does not set the error bit in the header if for
| |
| protected mode). Warnings have the following format:
| |
|
| |
| location: ERROR L4xxx: message text
| |
|
| |
| In these messages, location is the input file associated with the error, or
| |
| LINK if there is no input file.
| |
|
| |
| If the input file is an .OBJ or .LIB file and has a module name, the module
| |
| name is enclosed in parentheses, as shown in the following examples:
| |
|
| |
| SLIBC.LIB(_FILE)
| |
| MAIN.OBJ(MAIN.C)
| |
| TEXT.OBJ
| |
|
| |
| The following error messages may appear when you link object files with LINK:
| |
|
| |
| L1001 option : OPTION NAME AMBIGUOUS
| |
| A unique option name does not appear after the option indicator (/). For
| |
| example, the command
| |
|
| |
| LINK /N MAIN;
| |
|
| |
| produces this error, since LINK cannot tell which of the three options
| |
| beginning with the letter N is intended.
| |
|
| |
| L1002 option : UNRECOGNIZED OPTION NAME
| |
| An unrecognized character followed the option indicator (/), as in the
| |
| following example:
| |
|
| |
| LINK /ABCDEF MAIN;
| |
|
| |
| L1003 option : MAP SYMBOL LIMIT TOO HIGH
| |
| The specified symbol limit value following the MAP option is greater than
| |
| 32768, or there is not enough memory to increase the limit to the
| |
| requested value.
| |
|
| |
| L1004 option : INVALID NUMERIC VALUE
| |
| An incorrect value appeared for one of the linker options. For example,
| |
| a character string is entered for an option that requires a numeric
| |
| value.
| |
|
| |
| L1006 option : STACK SIZE EXCEEDS 65534 BYTES
| |
| The size you specified for the stack in the /STACK option of the LINK
| |
| command is more than 65534 bytes.
| |
|
| |
| L1007 option : INTERRUPT NUMBER EXCEEDS 255
| |
| You gave a number greater than 255 as a value for the /OVERLAYINTERRUPT
| |
| option.
| |
|
| |
| L1008 option : SEGMENT LIMIT TOO HIGH
| |
| The specified limit on the /SEGMENTS option is greater than 3072.
| |
|
| |
| L1009 option : CPARMAXALLOC : ILLEGAL VALUE
| |
| The number you specified in the /CPARMAXALLOC option is not in the range
| |
| 1 to 65535.
| |
|
| |
| L1020 NO OBJECT MODULES SPECIFIED
| |
| You did not specify any object-file names to the linker.
| |
|
| |
| L1021 CANNOT NEST RESPONSE FILES
| |
| A response file occurs within a response file, which DOS 4.00 does not
| |
| permit.
| |
|
| |
| L1022 RESPONSE LINE TOO LONG
| |
| A line in a response file is longer than 127 characters.
| |
|
| |
| L1023 TERMINATED BY USER
| |
| You entered CTRL+C.
| |
|
| |
| L1024 NESTED RIGHT PARENTHESES
| |
| You typed the contents of an overlay incorrectly on the command line.
| |
|
| |
| L1025 NESTED LEFT PARENTHESES
| |
| You typed the contents of an overlay incorrectly on the command line.
| |
|
| |
| L1026 UNMATCHED RIGHT PARENTHESIS
| |
| A left parenthesis is missing from the contents specification of an
| |
| overlay on the command line.
| |
|
| |
| L1027 UNMATCHED LEFT PARENTHESIS
| |
| A right parenthesis is missing from the contents specification of an
| |
| overlay on the command line.
| |
|
| |
| L1041 RESIDENT-NAME TABLE OVERFLOW
| |
| The total length of all resident names, plus three bytes per name, is
| |
| greater than 65534.
| |
|
| |
| L1042 NONRESIDENT-NAME TABLE OVERFLOW
| |
| The total length of all nonresident names, plus three bytes per name, is
| |
| greater than 65534.
| |
|
| |
| L1043 RELOCATION TABLE OVERFLOW
| |
| There are more than 65536 load-time relocations for a single segment.
| |
|
| |
| L1045 TOO MANY TYPDEF RECORDS
| |
| An object module contains more than 255 TYPDEF records. These records
| |
| describe communal variables. This error can only appear with programs
| |
| produced by compilers that support communal variables.
| |
|
| |
| L1046 TOO MANY EXTERNAL SYMBOLS IN ONE MODULE
| |
| An object module specifies more than the limit of 1023 external symbols.
| |
| You need to break the module into smaller parts.
| |
|
| |
| L1047 TOO MANY GROUP, SEGMENT, AND CLASS NAMES IN ONE MODULE
| |
| The program contains too many group, segment, and class names. You need
| |
| to reduce the number of groups, segments, or classes, and recreate the
| |
| object files.
| |
|
| |
| L1048 TOO MANY SEGMENTS IN ONE MODULE
| |
| An object module has more than 255 segments. Split the module or combine
| |
| segments.
| |
|
| |
| L1049 TOO MANY SEGMENTS
| |
| The program has more than the maximum number of segments.
| |
| The SEGMENTS option specifies the maximum allowed number; the default is
| |
| 128. Relink using the /SEGMENTS option with an appropriate number of
| |
| segments.
| |
|
| |
| L1050 TOO MANY GROUPS IN ONE MODULE
| |
| The linker found more than 21 group definitions (GRPDEF) in a single
| |
| module. Reduce the number of group definitions or split the module.
| |
|
| |
| L1051 TOO MANY GROUPS
| |
| The program defines more than 20 groups, not counting DGROUP. Reduce the
| |
| number of groups.
| |
|
| |
| L1052 TOO MANY LIBRARIES
| |
| An attempt is made to link with more than 32 libraries. Combine
| |
| libraries, or use modules that require fewer libraries.
| |
|
| |
| L1053 SYMBOL TABLE OVERFLOW
| |
| The program has more than 256K bytes of symbolic information, (such as
| |
| public, external, segment, group, class, and file names). Combine
| |
| modules or segments and recreate the object files. Eliminate as many
| |
| public symbols as possible.
| |
|
| |
| L1054 OUT OF MEMORY: REDUCE # IN /SEGMENTS: # OR /MAP: #
| |
| The linker does not have enough memory to allocate tables describing the
| |
| number of segments requested. (The default is 128 or the value specified
| |
| with the /SEGMENTS option.) Try linking again using the /SEGMENTS option
| |
| to select a smaller number of segments (for example, use 64 if the
| |
| default was used previously), or free some memory by eliminating resident
| |
| programs or shells.
| |
|
| |
| L1056 TOO MANY OVERLAYS
| |
| The program defines more than 63 overlays.
| |
|
| |
| L1057 DATA RECORD TOO LARGE
| |
| A LEDATA record (in an object module) contained more than 1024 bytes of
| |
| data. This is a translator (compiler or assembler) error. Note which
| |
| translator (compiler or assembler) produced the incorrect object module
| |
| and the circumstances, and contact your authorized IBM dealer.
| |
|
| |
| L1070 SEGMENT SIZE EXCEEDS 64K
| |
| A single segment contains more than 64KB of code or data. Try compiling,
| |
| or assembling, and linking using the large model.
| |
|
| |
| L1071 SEGMENT _TEXT LARGER THAN 65520 BYTES
| |
| This error is likely to occur only in small-model C programs, but it can
| |
| occur when any program with a segment named _TEXT is linked using the
| |
| /DOSSEG option of the LINK command. Small-model C programs must reserve
| |
| code addresses 0 and 1; this is increased to 16 for alignment purposes.
| |
|
| |
| L1072 COMMON AREA LONGER THAN 65536 BYTES
| |
| The program has more than 64KB of communal variables. This error cannot
| |
| appear with object files produced by the IBM Macro Assembler/2. It
| |
| occurs only with programs or other compilers that support communal
| |
| variables.
| |
|
| |
| L1073 FILE-SEGMENT LIMIT EXCEEDED
| |
| There are more than 255 physical or file segments.
| |
|
| |
| L1074 name : GROUP LARGER THAN 64KB
| |
| A group contained segments which total more than 65536 bytes.
| |
|
| |
| L1075 ENTRY TABLE LARGER THAN 65535 BYTES
| |
| You have exceeded a linker table size limit because of too many entry
| |
| names. Reduce the number of names in the modules you are linking.
| |
|
| |
| L1080 CANNOT OPEN LIST FILE
| |
| The disk or the root directory is full, or an invalid filename was
| |
| entered. Delete or move files to make space, or link again with a valid
| |
| filename.
| |
|
| |
| L1081 OUT OF SPACE FOR RUN FILE
| |
| The disk on which .EXE file is being written is full.
| |
| Free more space on the disk and restart the linker.
| |
|
| |
| L1083 CANNOT OPEN RUN FILE
| |
| The disk or the root directory is full. Delete or move files to make
| |
| space.
| |
|
| |
| L1084 CANNOT CREATE TEMPORARY FILE
| |
| The disk or root directory is full. Free more space in the directory and
| |
| restart the linker.
| |
|
| |
| L1085 CANNOT OPEN TEMPORARY FILE
| |
| The disk or the root directory is full. Delete or move files to make
| |
| space.
| |
|
| |
| L1086 SCRATCH FILE MISSING
| |
| Internal error. You should note the conditions when the error occurs and
| |
| contact your authorized IBM Computer dealer.
| |
|
| |
| L1087 UNEXPECTED END-OF-FILE ON SCRATCH FILE
| |
| The disk with the temporary linker-output file is removed.
| |
|
| |
| L1088 OUT OF SPACE FOR LIST FILE
| |
| The disk on which the listing file is being written is full. Free more
| |
| space on the disk and restart the linker.
| |
|
| |
| L1089 filename : CANNOT OPEN RESPONSE FILE
| |
| The linker could not find the specified response file. This usually
| |
| indicates a typing error. Correct the error.
| |
|
| |
| L1090 CANNOT REOPEN LIST FILE
| |
| The original disk is not replaced at the prompt. Restart the linker.
| |
|
| |
| L1091 UNEXPECTED END-OF-FILE ON LIBRARY
| |
| The disk containing the library probably was removed. Replace the disk
| |
| containing the library and run the linker again.
| |
|
| |
| L1093 filename: OBJECT FILE NOT FOUND
| |
| The linker could not find the specified object file.
| |
|
| |
| L1101 INVALID OBJECT MODULE
| |
| One of the object modules is not valid.
| |
| If the error persists after recompiling, contact your authorized IBM
| |
| dealer.
| |
|
| |
| L1102 UNEXPECTED END-OF-FILE
| |
| An invalid format for a library was found.
| |
|
| |
| L1103 ATTEMPT TO ACCESS DATA OUTSIDE SEGMENT BOUNDS
| |
| A data record in an object module specified data extending beyond the end
| |
| of a segment. This is a translator error. Note which translator
| |
| (compiler or assembler) produced the incorrect object module and the
| |
| circumstances, and contact your authorized IBM dealer.
| |
|
| |
| L1104 filename : NOT VALID LIBRARY
| |
| The specified file is not a valid library file. This error causes the
| |
| linker to stop running.
| |
|
| |
| L1113 UNRESOLVED COMDEF; INTERNAL ERROR
| |
| You should note the conditions when the error occurs and contact your
| |
| authorized IBM dealer.
| |
|
| |
| L1114 FILE NOT SUITABLE FOR /EXEPACK; RELINK WITHOUT
| |
| For the linked program, the size of the packed load image plus the
| |
| packing overhead is larger than that of the unpacked load image. Relink
| |
| without the EXEPACK option.
| |
|
| |
| L2001 FIXUP(S) WITHOUT DATA
| |
| A FIXUP record occurred without a data record immediately preceding it.
| |
| This is probably a compiler error.
| |
|
| |
| L2002 FIXUP OVERFLOW number IN FRAME SEG segname TARGET SEG segname
| |
| TARGET OFFSET number
| |
| The following conditions can cause this error:
| |
|
| |
| A group is larger than 64KB.
| |
| The program contains an intersegment short jump or intersegment short
| |
| call.
| |
| The name of a data item in the program conflicts with that of a
| |
| subroutine in a library included in the link.
| |
| An EXTRN declaration in an assembler-language source file appeared inside
| |
| the body of a segment.
| |
|
| |
| This example may cause this error:
| |
|
| |
| code SEGMENT public 'CODE'
| |
| EXTRN main:far
| |
| start PROC far
| |
| call main
| |
| ret
| |
| start ENDP
| |
| code ENDS
| |
|
| |
| The following construction is preferred:
| |
|
| |
| EXTRN main:far
| |
| code SEGMENT public 'CODE'
| |
| start PROC far
| |
| call main
| |
| ret
| |
| start ENDP
| |
| code ENDS
| |
|
| |
| Revise the source file and recreate the object file.
| |
|
| |
| L2003 INTERSEGMENT SELF-RELATIVE FIXUP
| |
| An intersegment self-relative fixup is not allowed.
| |
|
| |
| L2004 LOBYTE-TYPE FIXUP OVERFLOW
| |
| A LOBYTE fixup produced an address overflow.
| |
|
| |
| L2005 FIXUP TYPE UNSUPPORTED
| |
| A fixup type occurred that is not supported by the linker. This is
| |
| (probably) a compiler error. You should note the conditions when the
| |
| error occurs and contact your authorized IBM dealer.
| |
|
| |
| L2010 TOO MANY FIXUPS IN LIDATA RECORD
| |
| There are more fixups applying to a LIDATA record than will fit in the
| |
| linker's 1024-byte buffer. The buffer is divided between the data in the
| |
| LIDATA record and run-time relocation items, which are eight bytes
| |
| apiece, so the maximum varies from 0 to 128. This is probably a compiler
| |
| error.
| |
|
| |
| L2011 name : NEAR/HUGE CONFLICT
| |
| Conflicting NEAR and HUGE attributes are given for a communal variable.
| |
| This error can occur only with programs produced by compilers that
| |
| support communal variables.
| |
|
| |
| L2012 name : ARRAY-ELEMENT SIZE MISMATCH
| |
| A far communal array is declared with two or more different array-element
| |
| sizes (for example, an array declared once as an array of characters and
| |
| once as an array of real numbers). This error cannot occur with object
| |
| files produced by the IBM Macro Assembler/2. It occurs only with
| |
| compilers that support far communal arrays.
| |
|
| |
| L2013 LIDATA RECORD TOO LARGE
| |
| A LIDATA record in an object module contains more than 512 bytes of data.
| |
| Most likely, an assembly module contains a very complex structure
| |
| definition or a series of deeply-nested DUP operators. For example, the
| |
| following structure definition causes this error:
| |
|
| |
| alpha DB 10DUP(11 DUP(12 DUP(13 DUP(...))))
| |
|
| |
| Simplify the structure definition and reassemble. (LIDATA is a DOS
| |
| term.)
| |
|
| |
| L2024 name : SYMBOL ALREADY DEFINED
| |
| One of the special overlay symbols required for overlay support is
| |
| defined by an object.
| |
|
| |
| L2025 name : SYMBOL DEFINED MORE THAN ONCE
| |
| Remove the extra symbol definition from the object file.
| |
|
| |
| L2028 AUTOMATIC DATA SEGMENT PLUS HEAP EXCEED 64K
| |
| The size of DGROUP near data plus requested heap size is greater than
| |
| 64K.
| |
|
| |
| L2029 UNRESOLVED EXTERNALS
| |
| One or more symbols are declared to be external in one or more modules,
| |
| but they are not publicly defined in any of the modules or libraries.
| |
| A list of the unresolved external references appears after the message,
| |
| as shown in the following example:
| |
|
| |
| _exit in file(s)
| |
| main.obj (main.c)
| |
| _fopen in files(s)
| |
| fileio.obj(fileio.c) main.obj(main.c)
| |
|
| |
| The name that comes before IN FILE(S) is the unresolved external symbol.
| |
| On the next line is a list of object modules that have made references to
| |
| this symbol. This message and the list are also written to the map file,
| |
| if one exists.
| |
|
| |
| L2030 STARTING ADDRESS NOT CODE (USE CLASS 'CODE')
| |
| You specified to the linker a starting address which is a segment that is
| |
| not a CODE segment. Reclassify the segment to CODE, or correct the
| |
| starting point.
| |
|
| |
| L4001 FRAME-RELATIVE FIXUP, FRAME IGNORED
| |
| A fixup occurred with a frame segment different from the target segment
| |
| where either the frame or the target segment is not absolute.
| |
|
| |
| L4002 FRAME-RELATIVE ABSOLUTE FIXUP
| |
| A fixup occurred with a frame segment different from the target segment
| |
| where both frame and target segments were absolute.
| |
|
| |
| L4012 LOAD-HIGH DISABLES EXEPACK
| |
| You must select either the /HIGH or EXEPACK option. They cannot be used
| |
| together.
| |
|
| |
| L4014 INVALID OPTION FOR OLD-FORMAT EXECUTABLE FILE IGNORED
| |
| If a DOS 4.00 format program is produced, the options /ALIGNMENT,
| |
| /NOFARCALLTRANSLATION, and /PACKCODE are meaningless, and the linker
| |
| ignores them.
| |
|
| |
| L4020 name : CODE-SEGMENT SIZE EXCEEDS 65500
| |
| Code segments of length 65501 through 65536 may be unreliable on the
| |
| 80286 processor.
| |
|
| |
| L4021 NO STACK SEGMENT
| |
| The program does not contain a stack segment defined with STACK combine
| |
| type. This message should not appear for modules whose source code was
| |
| compiled by the high-level language compilers supported by DOS 4.00, but
| |
| it could appear for an assembler-language module. Normally, every
| |
| program should have a stack segment with the combine type specified as
| |
| STACK. You can ignore this message if you have a specific reason for not
| |
| defining a stack, or for defining one without the STACK combine type.
| |
|
| |
| L4022 name1, name2 : GROUPS OVERLAP
| |
| Two groups are defined so that one starts in the middle of another. This
| |
| may occur if you defined segments in an assembly file and did not
| |
| correctly order the segments by class.
| |
|
| |
| L4028 name : SEGMENT ALREADY DEFINED
| |
| A segment is defined more than once with the same name. Segments must
| |
| have unique names for the linker. Only the first definition of a name is
| |
| recognized.
| |
|
| |
| L4029 name : DGROUP SEGMENT CONVERTED TO TYPE DATA
| |
| A segment which is a member of DGROUP is defined as type CODE in an
| |
| object file.
| |
|
| |
| L4030 name : SEGMENT ATTRIBUTES CHANGED TO CONFORM WITH AUTOMATIC DATA
| |
| SEGMENT
| |
| The segment named name is defined in DGROUP, but the shared attribute is
| |
| in conflict with the instance attribute. For example, the shared
| |
| attribute is NONSHARED and the instance is SINGLE, or the shared
| |
| attribute is SHARED and the instance attribute is MULTIPLE. The bad
| |
| segment is forced to have the right shared attribute and the link
| |
| continues. The image is not marked as having errors.
| |
|
| |
| L4031 name : SEGMENT DECLARED IN MORE THAN ONE GROUP
| |
| A segment is declared to be a member of two different groups. Correct
| |
| the source file and recreate the object files.
| |
|
| |
| L4032 name : CODE-GROUP SIZE EXCEEDS 65500 BYTES
| |
| Code segments of length 65501 through 65536 may be unreliable on the
| |
| 80286 processor.
| |
|
| |
| L4034 MORE THAN 239 OVERLAY SEGMENTS; EXTRA PUT IN ROOT
| |
| You specified an overlay structure containing more than 239 segments.
| |
| The extra segments have been assigned to the root overlay.
| |
|
| |
| L4036 NO AUTOMATIC DATA SEGMENT
| |
| No group named DGROUP is declared.
| |
|
| |
| L4050 TOO MANY PUBLIC SYMBOLS
| |
| The /MAP option is used to request a sorted listing of public symbols in
| |
| the map file, but there were too many symbols to sort. (The default is
| |
| 2048 symbols.) The linker produces an unsorted listing of the public
| |
| symbols. Relink using /MAP:number.
| |
|
| |
| L4051 filename : CANNOT FIND LIBRARY
| |
| The linker could not find the specified file. Enter a new filename, a
| |
| new path specification, or both.
| |
|
| |
| L4053 VM.TMP : ILLEGAL FILE NAME; IGNORED
| |
| VM.TMP appears as an object-file name. Rename the file and rerun the
| |
| linker.
| |
|
| |
| L4054 filename : CANNOT FIND FILE
| |
| The linker could not find the specified file. Enter a new filename, a
| |
| new path specification, or both.
| |
|
| |
| LINKER LIMITS
| |
|
| |
| The table below summarizes the limits imposed by the linker. However, your
| |
| program may be adjusted so that the linker will set aside its limits to
| |
| accommodate it.
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | ITEM LIMIT |
| |
| +---------------------------------------------------------------------------+
| |
| | Symbol table 256KB |
| |
| +---------------------------------------------------------------------------+
| |
| | Load-time Default is 32KB. If /EXEPACK is used, the maximum |
| |
| | relocations is 512KB. |
| |
| +---------------------------------------------------------------------------+
| |
| | Public symbols The range 7700 through 8700 can be used as a |
| |
| | guideline for the maximum number of public symbols |
| |
| | allowed; the actual maximum depends on the program. |
| |
| +---------------------------------------------------------------------------+
| |
| | External symbols per 1023 |
| |
| | module |
| |
| +---------------------------------------------------------------------------+
| |
| | Groups Maximum number is 21, but the linker always defines |
| |
| | DGROUP so the effective maximum is 20. |
| |
| +---------------------------------------------------------------------------+
| |
| | Overlays 63 |
| |
| +---------------------------------------------------------------------------+
| |
| | Segments 128 by default; however, this maximum can be set as |
| |
| | high as 3072 by using the /SEGMENTS option of the |
| |
| | LINK command. |
| |
| +---------------------------------------------------------------------------+
| |
| | Libraries 32 |
| |
| +---------------------------------------------------------------------------+
| |
| | Group definitions 21 |
| |
| | per module |
| |
| +---------------------------------------------------------------------------+
| |
| | Segments per module 255 |
| |
| +---------------------------------------------------------------------------+
| |
| | Stack 64KB |
| |
| +---------------------------------------------------------------------------+
| |
| </PRE>
| |
|
| |
|
| ==Chapter 9== | | ==The Utilities Diskette== |
| <PRE>
| | A utilities diskette is included with this book. It contains a listing of the following utilities, and the description of each utility, to help |
| CHAPTER 9. CONVERTING FILE FORMATS 8
| | programmers develop an application program: |
| The EXE2BIN.EXE Utility 13
| | *DEBUG.COM - A utility to isolate and determine errors in executable programs. |
| Entering Input to EXE2BIN 34
| | *EXE2BIN.EXE - A utility to convert executable file formats (.EXE) to .COM formats to make them more compact and, therefore, load more quickly. |
| Two Types of Conversion 61
| | *LIB.EXE - A utility that allows the programmer to build and edit object libraries. |
| Device Drivers 66
| | *LINK.EXE - A utility to translate object code to executable code. |
| Standard .COM File 100
| | *VDISK.ASM - A fully documented programming example of a device driver. However, this example does not reflect the current level of VDISK.SYS. |
|
| |
| CHAPTER 9. CONVERTING FILE FORMATS
| |
|
| |
| This chapter describes how to use EXE2BIN.EXE on your utilities diskette to
| |
| convert an .EXE file to a .COM file format.
| |
|
| |
| THE EXE2BIN.EXE UTILITY
| |
|
| |
| EXE2BIN is useful if you have a simple .EXE file that doesn't need the DOS
| |
| preparation that an .EXE file usually requires, such as telling the program
| |
| its location in memory and setting up a stack for it to use. Converting an
| |
| .EXE file to a .COM format makes the file more compact and enables it to load | |
| faster.
| |
|
| |
| To qualify for EXE2BIN conversion, your .EXE file has to meet these criteria:
| |
|
| |
| The file format must be a valid .EXE one, as produced by the IBM Linker.
| |
| Actual code and data in the file (the resident portion of the program)
| |
| must be less than 64KB.
| |
| Only one segment can be declared; therefore, the file cannot define a
| |
| STACK segment.
| |
| If the file is to be loaded by the DOS 4.00 command processor, the IBM
| |
| Macro Assembler ORG statement must set the location pointer of the file
| |
| at 100H.
| |
| The IBM Macro Assembler END statement must specify the first location as
| |
| the starting address.
| |
|
| |
| ENTERING INPUT TO EXE2BIN
| |
|
| |
| Input to EXE2BIN must be entered at the command line and has the following
| |
| format:
| |
|
| |
| Note that the only parameter required by EXE2BIN is the filename of the input
| |
| file. If you specify only a filename, EXE2BIN looks for a file with an .EXE
| |
| extension in the current directory of the default drive. The output file
| |
| created by a successful conversion has the same filename with a .BIN
| |
| extension.
| |
|
| |
| For example, suppose you have a file called MYFILE.EXE in your current
| |
| working directory that meets EXE2BIN's conversion criteria. To have EXE2BIN
| |
| convert the file, you can enter:
| |
|
| |
| EXE2BIN MYFILE
| |
|
| |
| EXE2BIN creates a memory image of MYFILE.EXE and copies it to the output
| |
| file. The new file named MYFILE.BIN is placed in your current working
| |
| directory.
| |
|
| |
| Of course, you can specify any of these optional parameters. If you specify
| |
| a drive and path for your input file and do not specify an output
| |
| specification, the output file is placed on the current drive and directory.
| |
|
| |
| NOTE: This is a change from previous versions of DOS.
| |
|
| |
| TWO TYPES OF CONVERSION
| |
|
| |
| Two types of .EXE file conversion are possible, depending on how the entry
| |
| point of your program is defined.
| |
|
| |
| DEVICE DRIVERS
| |
|
| |
| The first type of conversion is for a program that will be loaded at the
| |
| absolute memory address specified by a user application or by DOS 4.00 at
| |
| system initialization. An example of this kind of program is a device
| |
| driver. | |
|
| |
| CS:IP is not specified in the program (the .EXE file header contains 0:0 as
| |
| the program's entry point). Segment fixups are allowed in this type of
| |
| conversion. If segment fixups are necessary, (that is, your program contains
| |
| instructions requiring segment relocation), you are prompted for the fixup
| |
| value. Here are some examples of code that will cause prompting for fixup
| |
| values:
| |
|
| |
| You have used the SEG operator:
| |
|
| |
| symbol1 db "e:\filename",0
| |
| symbol2 dw SEG symbol1 ;explicit use of SEG
| |
| symbol3 dw symbol1 ;implicit use of OFFSET
| |
|
| |
| You have used a segment name as an immediate field of instruction:
| |
|
| |
| myseg SEGMENT PUBLIC
| |
|
| |
| .
| |
| .
| |
| .
| |
| MOV AX,MYSEG ; fixup
| |
|
| |
| The fixup value is the absolute segment at which the program is to be loaded.
| |
|
| |
| The DOS 4.00 command processor is not capable of properly loading this type
| |
| of program.
| |
|
| |
| STANDARD .COM FILE
| |
|
| |
| To produce standard .EXE files that are suitable for EXE2BIN conversion, you
| |
| must use the Macro Assembler ORG statement to set the location pointer of the
| |
| file at 100H and specify the first location as the start address in the END
| |
| statement.
| |
|
| |
| ORG 100H
| |
| START
| |
| .
| |
| .
| |
| .
| |
| END START
| |
|
| |
| When EXE2BIN sees that CS:IP is specified as 0000:100H, it assumes that the
| |
| file is to be run as a standard .COM file, with the location pointer set at
| |
| 100H by the ORG statement. No segment fixups are possible because standard
| |
| .COM files must be segment relocatable. Once the conversion is complete, you
| |
| may rename the resultant file to a .COM extension. Then the command
| |
| processor is capable of loading and executing the program in the same manner
| |
| as the .COM programs supplied on your DOS 4.00 diskette.
| |
|
| |
| If your file does not fit one of these two descriptions, or if it is similar
| |
| to the standard .COM file description but has segment fixups, the following
| |
| message is displayed:
| |
|
| |
| File cannot be converted
| |
|
| |
| This message is also displayed if the file is not a valid .EXE file.
| |
|
| |
| See the IBM Macro Assembler manual for a comparison of .EXE and .COM file
| |
| structures. Skeleton structures for .EXE files and .COM files are provided
| |
| on the MASM diskette.
| |
| </PRE>
| |
|
| |
|
| ==Chapter 10== | | ==Links== |
| <PRE>
| | *[https://archive.org/download/bitsavers_ibmpcdos15lReferenceJul88_10507385/15F0256_DOS_4.0_Technical_Reference_Jul88.pdf PDF] |
| CHAPTER 10. DEBUGGING A PROGRAM 32
| | *{{L-IBMAnnUS|ZP88-0364}} 1988-07-20 - Disk Operating System Version 4.00 |
| The DEBUG Utility 37
| |
| Starting the DEBUG.COM Program 46
| |
| Entering Commands at the DEBUG Prompt 67
| |
| DEBUG Command Summary 103
| |
| The DEBUG Work Space 181
| |
| A (Assemble) Command 225
| |
| C (Compare) Command 348
| |
| D (Dump) Command 400
| |
| E (Enter) Command 504
| |
| F (Fill) Command 620
| |
| G (Go) Command 669
| |
| H (Hexarithmetic) Command 771
| |
| I (Input) Command 789
| |
| L (Load) Command 811 | |
| M (Move) Command 919
| |
| N (Name) Command 973
| |
| O (Output) Command 1019
| |
| P (Proceed) Command 1040
| |
| Q (Quit) Command 1090
| |
| R (Register) Command 1113
| |
| S (Search) Command 1263
| |
| T (Trace) Command 1321
| |
| U (Unassemble) Command 1390
| |
| W (Write) Command 1513
| |
| XA (EMS Allocate) Command 1645
| |
| XD (EMS Deallocate) Command 1672
| |
| XM (EMS Map) Command 1699
| |
| XS (EMS Status) Command 1727
| |
| DEBUG Error Messages 1759
| |
| | | |
| CHAPTER 10. DEBUGGING A PROGRAM
| | [[Category:DOS Documentation]] |
|
| |
| This chapter describes how to use the DEBUG.COM program on the utilities
| |
| diskette to identify and fix problems in your programs.
| |
|
| |
| THE DEBUG UTILITY
| |
|
| |
| DEBUG provides a controlled testing environment that enables you to monitor
| |
| the execution of a program. You can make changes directly to a .COM or an
| |
| .EXE file and execute the file immediately to determine whether your changes
| |
| fixed a problem. You do not need to reassemble source code files first.
| |
| DEBUG allows you to load, alter, or display any file and to execute object
| |
| files as well.
| |
|
| |
| STARTING THE DEBUG.COM PROGRAM
| |
|
| |
| To start DEBUG, enter information in the following format:
| |
|
| |
| You can enter just the DEBUG command, or you can include a file
| |
| specification. The parameters parm1 and parm2 represent input and output
| |
| specifications of the program you are debugging. For example, suppose you
| |
| wanted to monitor the execution of the DOS 4.00 DISKCOMP utility. You enter:
| |
|
| |
| DEBUG DISKCOMP.COM A: B:
| |
|
| |
| The DEBUG program loads DISKCOMP into memory and displays the DEBUG prompt:
| |
|
| |
|
| |
| The hyphen (-) tells you DEBUG is ready to accept commands to alter, display,
| |
| or execute the contents of the program in memory.
| |
|
| |
| If you enter just DEBUG without a file specification, you can either work
| |
| with the present memory contents or you can load a required file into memory
| |
| using the DEBUG NAME and LOAD commands.
| |
|
| |
| ENTERING COMMANDS AT THE DEBUG PROMPT
| |
|
| |
| A DEBUG command consists of a single letter, usually followed by one or more
| |
| parameters. For example, the NAME command is entered at the DEBUG prompt as
| |
| a single letter followed by a file specification:
| |
|
| |
| -N MYPROG
| |
|
| |
| A command and its parameters can be entered in uppercase, lowercase, or a
| |
| combination of both. The command and its parameters can be separated by
| |
| delimiters; however, delimiters are only required between two consecutive
| |
| hexadecimal values. Thus, the following DUMP commands are equivalent:
| |
|
| |
| dcs:100 110
| |
| d cs:100 110
| |
| d,cs:100,110
| |
|
| |
| A command is activated only after you press the Enter key. If you want to
| |
| terminate a command and return to the DEBUG prompt, simultaneously press the
| |
| Ctrl and Break keys.
| |
|
| |
| For commands producing a large amount of output, you can simultaneously press
| |
| the Ctrl and Num Lock keys (or Pause key if available) to suspend the display
| |
| and then press any key to restart the display, or you can redirect the
| |
| command's output to a file.
| |
|
| |
| When DEBUG encounters a syntax error in a line, it displays the line with the
| |
| error identified as follows:
| |
|
| |
| d cs:100 CS:100
| |
| &hat.error 110
| |
|
| |
| In this example, the DUMP command expects the second address to contain only
| |
| a hexadecimal offset value. It finds the S, which is not a hexadecimal
| |
| character.
| |
|
| |
| DEBUG COMMAND SUMMARY
| |
|
| |
| The table below lists the DEBUG commands and describes the debugging
| |
| operations you can perform with them. Complete format descriptions and
| |
| examples for each command can be found starting on page 10-4.
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | COMMAND TASK DESCRIPTION |
| |
| +---------------------------------------------------------------------------+
| |
| | A Assemble IBM Macro Assembler statements directly into memory. |
| |
| | (Assemble) |
| |
| +---------------------------------------------------------------------------+
| |
| | C Compare the contents of two blocks of memory. |
| |
| | (Compare) |
| |
| +---------------------------------------------------------------------------+
| |
| | D (Dump) Dump the contents of a portion of memory to the display or |
| |
| | redirect it to a file. |
| |
| +---------------------------------------------------------------------------+
| |
| | E (Enter) Make changes to bytes in memory. |
| |
| +---------------------------------------------------------------------------+
| |
| | F (Fill) Fill a range of memory with byte values. |
| |
| +---------------------------------------------------------------------------+
| |
| | G (Go) Execute the program in memory from one address to the |
| |
| | breakpoint address and then display the next instruction. |
| |
| +---------------------------------------------------------------------------+
| |
| | H (Hex) Add and subtract two hexadecimal values and display the |
| |
| | results. |
| |
| +---------------------------------------------------------------------------+
| |
| | I (Input) Display the input in the first byte next to the port. |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | COMMAND TASK DESCRIPTION |
| |
| +---------------------------------------------------------------------------+
| |
| | L (Load) Load the contents of absolute disk sectors or a file |
| |
| | specified by the NAME command into memory. |
| |
| +---------------------------------------------------------------------------+
| |
| | M (Move) Copy the contents of a block of memory to another location. |
| |
| +---------------------------------------------------------------------------+
| |
| | N (Name) Set up file control blocks and file specification information |
| |
| | for LOAD and WRITE commands. |
| |
| +---------------------------------------------------------------------------+
| |
| | O (Output) Send a byte to an output port. |
| |
| +---------------------------------------------------------------------------+
| |
| | P Execute a subroutine call, loop instruction, interrupt, or |
| |
| | (Proceed) repeat string instruction and return control to DEBUG at the |
| |
| | next instruction. |
| |
| +---------------------------------------------------------------------------+
| |
| | Q (Quit) End the DEBUG session without saving the debugged program. |
| |
| +---------------------------------------------------------------------------+
| |
| | R Display the contents of registers and the settings of flags. |
| |
| | (Register) |
| |
| +---------------------------------------------------------------------------+
| |
| | S (Search) Search a range of memory for characters. |
| |
| +---------------------------------------------------------------------------+
| |
| | T (Trace) Execute one or more instructions in your program and display |
| |
| | the contents of registers and flags after each instruction. |
| |
| +---------------------------------------------------------------------------+
| |
| | U Translate the contents of memory into Assembler-like |
| |
| | (Unassemble)statements, displaying their addresses and hexadecimal |
| |
| | values. |
| |
| +---------------------------------------------------------------------------+
| |
| | W (Write) Write the debugged program to absolute disk sectors or to the |
| |
| | original file loaded with DEBUG. |
| |
| +---------------------------------------------------------------------------+
| |
| | XA Allocate a specified number of expanded memory pages to an |
| |
| | (Allocate) EMS handle. |
| |
| +---------------------------------------------------------------------------+
| |
| | XD Deallocate an EMS handle. |
| |
| | (Deallocate) |
| |
| +---------------------------------------------------------------------------+
| |
| | XM (Map) Map an EMS logical page to an EMS physical page from an EMS |
| |
| | handle. |
| |
| +---------------------------------------------------------------------------+
| |
| | XS Display the status of expanded memory. |
| |
| | (Status) |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| THE DEBUG WORK SPACE
| |
|
| |
| When the DEBUG program starts, the registers and flags are set to the
| |
| following values for the program being debugged:
| |
|
| |
| The segment registers (CS, DS, ES, and SS) are set to the bottom of free
| |
| memory; that is, the first segment after the end of the DEBUG program.
| |
| The Instruction Pointer (IP) is set to hex 0100.
| |
| The Stack Pointer (SP) is set to the end of the segment, or the bottom of
| |
| the transient portion of the program loader, whichever is lower. The
| |
|
| |
| segment size at offset 6 is reduced by hex 100 to allow for a stack that
| |
| size.
| |
| The remaining registers (AX, BX, CX, DX, BP, SI, and DI) are set to 0.
| |
| However, if you start the DEBUG program with a file specification, the CX
| |
| register contains the length of the file in bytes. If the file is
| |
| greater than 64KB, the length is contained in registers BX and CX (the
| |
| high portion in BX).
| |
| The initial state of the flags is:
| |
|
| |
| NV UP EI PL NZ NA PO NC
| |
|
| |
| The default disk transfer address is set to hex 80 in the code segment.
| |
|
| |
| All of available memory is allocated. At this point, the loaded program is
| |
| unable to allocate memory.
| |
|
| |
| .EXE Files
| |
|
| |
| If a file loaded by DEBUG has an extension of .EXE, DEBUG does the necessary
| |
| relocation and sets the segment registers, stack pointer, and instruction
| |
| pointer to the values defined in the file. The DS and ES registers, however,
| |
| point to the program segment prefix at the lowest available segment. The BX
| |
| and CX registers contain the size of the program that is smaller than the
| |
| file size.
| |
|
| |
| The program is loaded at the high end of memory if the appropriate parameter
| |
| was specified when the linker created the file.
| |
|
| |
| .HEX Files
| |
|
| |
| If a file loaded by DEBUG has an extension of .HEX, the file is assumed to be
| |
| in INTEL hex format, and is converted to executable form while being loaded.
| |
|
| |
| A (ASSEMBLE) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Assembles IBM Macro Assembler language statements directly into memory.
| |
|
| |
| FORMAT
| |
|
| |
| A[address]
| |
|
| |
| PARAMETERS
| |
|
| |
| address Use any of the following formats:
| |
|
| |
| A segment register plus an offset, such as CS:0100
| |
| A segment address plus an offset, such as 4BA:0100
| |
| An offset only, such as 100. In this case, the default
| |
| segment is used.
| |
|
| |
| COMMENTS
| |
|
| |
| All numeric input to the Assemble command is in hexadecimal. The assembly
| |
| statements you enter are assembled into memory at successive locations,
| |
| starting with the address specified in address. If no address is specified,
| |
| the statements are assembled into the area at CS:0100, if no previous
| |
| Assemble command was used, or into the location following the last
| |
| instruction assembled by a previous Assemble command. After all desired
| |
| statements have been entered, press the Enter key when you are prompted for
| |
| the next statement to return to the DEBUG prompt.
| |
|
| |
| DEBUG responds to invalid statements by displaying:
| |
|
| |
| &hat.error
| |
|
| |
| and re-displaying the current assemble address.
| |
|
| |
| DEBUG supports standard 8086/8088 assembly language syntax (and the 8087
| |
| instruction set), with the following rules:
| |
|
| |
| All numeric values entered are hexadecimal and can be entered as 1
| |
| through 4 characters.
| |
|
| |
| Prefix mnemonics are entered in front of the opcode to which they refer.
| |
| They can also be entered on a separate line.
| |
|
| |
| The segment override mnemonics are CS:, DS:, ES:, and SS:.
| |
|
| |
| String manipulation mnemonics must specify the string size. For example,
| |
| MOVSW must be used to move word strings and MOVSB must be used to move
| |
| byte strings.
| |
|
| |
| The mnemonic for the far return is RETF.
| |
|
| |
| The assembler will automatically assemble short, near, or far jumps and
| |
| calls depending on byte displacement to the destination address. These
| |
| can be overridden with the NEAR or FAR prefix. For example:
| |
|
| |
| 0100:0500 JMP 502 ;a 2 byte short jump
| |
| 0100:0502 JMP NEAR 505 ;a 3 byte near jump
| |
| 0100:0505 JMP FAR 50A ;a 5 byte far jump
| |
|
| |
| The NEAR prefix can be abbreviated to NE, but the FAR prefix cannot be
| |
| abbreviated.
| |
|
| |
| DEBUG cannot tell whether some operands refer to a word memory location
| |
| or a byte memory location. In this case, the data type must be
| |
| explicitly stated with the prefix WORD PTR or BYTE PTR. DEBUG will also
| |
| accept the abbreviations WO and BY. For example:
| |
|
| |
| NEG BYTE PTR [128]
| |
| DEC WO [SI]
| |
|
| |
| DEBUG also cannot tell whether an operand refers to a memory location or
| |
| to an immediate operand. DEBUG uses the common convention that operands
| |
| enclosed in square brackets refer to memory. For example:
| |
|
| |
| MOV AX,21 ;Load AX with 21H
| |
| MOV AX,[21] ;Load AX with the
| |
| contents of memory
| |
| location 21H
| |
|
| |
| Two popular pseudo-instructions have also been included. The DB opcode
| |
| assembles byte values directly into memory. The DW opcode assembles word
| |
| values directly into memory. For example:
| |
|
| |
| DB 1,2,3,4,'THIS IS AN EXAMPLE'
| |
| DB 'THIS IS A QUOTE: ''
| |
| DB 'THIS IS AN APOSTROPHE:''
| |
|
| |
| DW 1000,2000,3000,'BACH:'
| |
|
| |
| All forms of the register indirect commands are supported. For example:
| |
|
| |
| ADD BX,34[BP+2][SI-1]
| |
| POP [BP+DI]
| |
| PUSH [SI]
| |
|
| |
| All opcode synonyms are supported. For example:
| |
|
| |
| LOOPZ 100
| |
| LOOPE 100
| |
|
| |
| JA 200
| |
| JNBE 200
| |
|
| |
| For numeric co-processor opcodes the WAIT or FWAIT prefix must be
| |
| explicitly specified. For example:
| |
|
| |
| FWAIT FADD ST,ST(3) ;This line will
| |
| ;assemble a
| |
| ;FWAIT prefix
| |
| FLD TBYTE PTR [BX] ;This line will
| |
| ;not
| |
|
| |
| EXAMPLE
| |
|
| |
| C>debug
| |
| -a200
| |
| 08B4:0200 xor ax,ax
| |
| 08B4:0202 mov [bx],ax
| |
| 08B4:0204 ret
| |
| 08B4:0205
| |
|
| |
| C (COMPARE) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Compares the contents of two blocks of memory.
| |
|
| |
| FORMAT
| |
|
| |
| C range address
| |
|
| |
| PARAMETERS
| |
|
| |
| range Either of these two formats:
| |
|
| |
| An address followed by an offset, such as CS:100 110.
| |
| An address followed by L value, where value is the number of
| |
| hexadecimal bytes to be processed. For example, CS:100 L 10.
| |
|
| |
| The limit for range is hexadecimal 10000 or decimal 64KB. To
| |
| specify a range of 64KB within 4 hexadecimal characters, enter
| |
| 0000 or 0 for value.
| |
|
| |
| address Any of these three formats:
| |
|
| |
| A segment register plus an offset, such as CS:0100.
| |
| A segment address plus an offset, such as 4BA:0100.
| |
| An offset only, such as 100. In this case, the default
| |
| segment is used.
| |
|
| |
| COMMENTS
| |
|
| |
| The contents of the two blocks of memory are compared; the length of the
| |
| comparison is determined from the range. If unequal bytes are found, their
| |
| addresses and contents are displayed, in the form:
| |
|
| |
| addr1 byte1 byte2 addr2
| |
|
| |
| where, the first half (addr1 byte1) refers to the location and contents of
| |
| the mismatching locations in range, and the second half (byte2 addr2) refers
| |
| to the byte found in address.
| |
|
| |
| If you enter only an offset for the beginning address of range, the C command
| |
| assumes the segment contained in the DS register. To specify an ending
| |
| address for range, enter it with only an offset value.
| |
|
| |
| EXAMPLE
| |
|
| |
| C 100 L20 200
| |
|
| |
| The 32 bytes (hex 20) of memory beginning at DS:100 are compared with the 32
| |
| bytes beginning at DS:200. L20 is the range.
| |
|
| |
| D (DUMP) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Displays the contents of a portion of memory.
| |
|
| |
| FORMAT
| |
|
| |
| D [address]
| |
|
| |
| or
| |
|
| |
| D [range]
| |
|
| |
| PARAMETERS
| |
|
| |
| address Any of the following formats:
| |
|
| |
| A segment register plus an offset, such as CS:0100.
| |
| A segment address plus an offset, such as 4BA:0100.
| |
| An offset only, such as 100. In this case, the default
| |
| segment is used.
| |
|
| |
| range Either of these two formats:
| |
|
| |
| An address followed by an offset, such as CS:100 110.
| |
| An address followed by L value, where value is the number of
| |
| hexadecimal bytes to be processed. For example, CS:100 L 10.
| |
|
| |
| The limit for range is hexadecimal 10000 or decimal 64K bytes.
| |
| To specify a range of 64K bytes within 4 hexadecimal characters,
| |
| enter 0000 or 0 for value.
| |
|
| |
| COMMENTS
| |
|
| |
| The dump is displayed in two parts:
| |
|
| |
| 1. A hexadecimal portion. Each byte is displayed in hexadecimal.
| |
|
| |
| 2. An ASCII portion. The bytes are displayed as ASCII characters.
| |
| Unprintable characters (ASCII 0 to 31 and 127 to 255) are indicated by a
| |
| period.
| |
|
| |
| With a 40-column system display format, each line begins on an 8-byte
| |
| boundary and shows 8 bytes.
| |
|
| |
| With an 80-column system display format, each line begins on a 16-byte
| |
| boundary and shows 16 bytes. There is a hyphen between the 8th and 9th
| |
| bytes.
| |
|
| |
| NOTE: The first line may have fewer than 8 or 16 bytes if the starting
| |
| address of the dump is not on a boundary. In this case, the second
| |
| line of the dump begins on a boundary.
| |
|
| |
| The Dump command has two format options.
| |
|
| |
| OPTION 1
| |
|
| |
| Use this option to display the contents of hex 40 bytes (40-column mode) or
| |
| hex 80 bytes (80-column mode). For example:
| |
|
| |
| D address
| |
|
| |
| or
| |
|
| |
| D
| |
|
| |
| The contents are dumped starting with the specified address.
| |
|
| |
| If you do not specify an address, the D command assumes the starting address
| |
| is the location following the last location displayed by a previous D
| |
|
| |
| command. Thus, it is possible to dump consecutive 40-byte or 80-byte areas
| |
| by entering consecutive D commands without parameters.
| |
|
| |
| If no previous D command was entered, the location is offset hex 100 into the
| |
| segment originally initialized in the segment registers by DEBUG.
| |
|
| |
| NOTE: If you enter only an offset for the starting address, the D command
| |
| assumes the segment contained in the DS register.
| |
|
| |
| OPTION 2
| |
|
| |
| Use this option to display the contents of the specified address range. For
| |
| example:
| |
|
| |
| D range
| |
|
| |
| NOTE: If you enter only an offset for the starting address, the D command
| |
| assumes the segment contained in the DS register. If you specify an
| |
| ending address, enter it with only an offset value.
| |
|
| |
| For example:
| |
|
| |
| D cs:100 10C
| |
|
| |
| A 40-column display format might look like this:
| |
|
| |
| 04BA:0100 42 45 52 54 41 20 54 00
| |
| BERTA T.
| |
|
| |
| 04BA:0108 20 42 4F 52 47
| |
| BORG
| |
|
| |
| E (ENTER) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Replaces the contents of one or more bytes, starting at the specified
| |
| address, with the values contained in the list (see Option 1).
| |
|
| |
| Displays and allows modification of bytes in a sequential manner (see
| |
| Option 2).
| |
|
| |
| FORMAT
| |
|
| |
| E address [list]
| |
|
| |
| PARAMETERS
| |
|
| |
| address Any of the following formats:
| |
|
| |
| A segment register plus an offset, such as CS:0100.
| |
| A segment address plus an offset, such as 4BA:0100.
| |
| An offset only, such as 100. In this case, the default
| |
| segment is used.
| |
|
| |
| list A string of byte values. If you include a character string,
| |
| enclose the characters in single or double quotation marks. To
| |
| specify a quotation mark as a character within the string when it
| |
| is also used to delimit the string, type it twice.
| |
|
| |
| 'These ''quotes'' are correct.'
| |
| 'This one''s okay, too.'
| |
|
| |
| COMMENTS
| |
|
| |
| If you enter only an offset for the address, the E command assumes the
| |
| segment contained in the DS register.
| |
|
| |
| The Enter command has two format options.
| |
|
| |
| OPTION 1
| |
|
| |
| Use this option to place the list in memory beginning at the specified
| |
| address.
| |
|
| |
| E address list
| |
|
| |
| For example:
| |
|
| |
| E ds:100 F3 'xyz' 8D
| |
|
| |
| Memory locations ds:100 through ds:104 are filled with the 5 bytes specified
| |
| in the list.
| |
|
| |
| OPTION 2
| |
|
| |
| Use this option to display the address and the byte of a location, then the
| |
| system waits for your input.
| |
|
| |
| For example:
| |
|
| |
| E address
| |
|
| |
| Enter a 1- or 2-character hexadecimal value to replace the contents of the
| |
| byte; then take any one of the following actions:
| |
|
| |
| 1. Press the space bar to advance to the next address. Its contents are
| |
| displayed. If you want to change the contents take option 1, above.
| |
|
| |
| To advance to the next byte without changing the current byte, press the
| |
| space bar again.
| |
|
| |
| 2. Enter a hyphen to back up to the preceding address. A new line is
| |
| displayed with the preceding address and its contents. If you want to
| |
| change the contents, take option 1, above.
| |
|
| |
| To back up one more byte without changing the current byte, enter another
| |
| hyphen.
| |
|
| |
| 3. Press the Enter key to end the Enter command.
| |
|
| |
| NOTE: Display lines can have 4 or 8 bytes of data, depending on whether the
| |
| system display format is 40- or 80-column. Spacing beyond an 8-byte
| |
| boundary causes a new display line, with the beginning address, to be
| |
| started.
| |
|
| |
| For example:
| |
|
| |
| E cs:100
| |
|
| |
| might cause this display:
| |
|
| |
| 04BA:0100 EB.
| |
|
| |
| To change the contents of 04BA:0100 from hex EB to hex 41, enter 41.
| |
|
| |
| 04BA:0100 EB.41
| |
|
| |
| To see the contents of the next three locations, press the space bar three
| |
| times. The screen might look like this:
| |
|
| |
| 04BA:0100 EB.41 10. 00. BC.
| |
|
| |
| To change the contents of the current location (04BA:0103) from hex BC to hex
| |
| 42, enter 42.
| |
|
| |
| 04BA:0100 EB.41 10. 00. BC.42
| |
|
| |
| Now, suppose you want to back up and change the hex 10 to hex 6F. This is
| |
| what the screen looks like after entering two hyphens and the replacement
| |
| byte:
| |
|
| |
| 04BA:0100 EB.41 10.00. BC.42-
| |
| 04BA:0102 00.-
| |
| 04BA:0101 10.6F
| |
|
| |
| Press the Enter key to end the Enter command. The hyphen prompt will appear.
| |
|
| |
| F (FILL) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Fills the memory locations in the range with the values in the list.
| |
|
| |
| FORMAT
| |
|
| |
| F range list
| |
|
| |
| PARAMETERS
| |
|
| |
| range Either of these two formats:
| |
|
| |
| An address followed by an offset, such as CS:100 110
| |
| An address followed by L value, where value is the number of
| |
| hexadecimal bytes to be processed. For example, CS:100 L 10.
| |
|
| |
| The limit for range is hexadecimal 10000 or decimal 64K bytes.
| |
| To specify a range of 64K bytes within 4 hexadecimal characters,
| |
| enter 0000 or 0 for value.
| |
|
| |
| list A string of byte values. If you include a character string,
| |
| enclose the characters in single or double quotation marks. To
| |
| specify a quotation mark as a character within the string when it
| |
| is also used to delimit the string, type it twice.
| |
|
| |
| 'These ''quotes'' are correct.'
| |
| 'This one''s okay, too.'
| |
|
| |
| COMMENTS
| |
|
| |
| If the list contains fewer bytes than the address range, the list is used
| |
| repeatedly until all the designated memory locations are filled.
| |
|
| |
| If the list contains more bytes than the address range, the extra list items
| |
| are ignored.
| |
|
| |
| NOTE: If you enter only an offset for the starting address of the range, the
| |
| Fill command assumes the segment contained in the DS register.
| |
|
| |
| EXAMPLE
| |
|
| |
| F 4BA:100 L 5 F3 'XYZ' 8D
| |
|
| |
| Memory locations 04BA:100 through 04BA:104 are filled with the 5 bytes
| |
| specified. Remember that the ASCII values of the list characters are stored.
| |
| Thus, locations 100-104 will contain F3 58 59 5A 8D.
| |
|
| |
| G (GO) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Executes the program you are debugging.
| |
|
| |
| Stops the execution when the instruction at a specified address is reached
| |
| (breakpoint), and displays the registers, flags, and the next instruction to
| |
| be executed.
| |
|
| |
| FORMAT
| |
|
| |
| G [=address] [address [address...]]
| |
|
| |
| PARAMETERS
| |
|
| |
| address Any of the following formats:
| |
|
| |
| A segment register plus an offset, such as CS:0100.
| |
| A segment address plus an offset, such as 4BA:0100.
| |
| An offset only, such as 100. In this case, the default
| |
| segment is used.
| |
|
| |
| COMMENTS
| |
|
| |
| Program execution begins with the current instruction, whose address is
| |
| determined by the contents of the CS and IP registers, unless overridden by
| |
| the =address parameter (the = must be entered). If =address is specified,
| |
| program execution begins with CS:=address.
| |
|
| |
| The Go command has two format options.
| |
|
| |
| OPTION 1
| |
|
| |
| Use this option to execute the program you are debugging without breakpoints.
| |
| For example:
| |
|
| |
| G [=address]
| |
|
| |
| This option is useful when testing program execution with different
| |
| parameters each time. (Refer to the Name command.) Be certain the CS:IP
| |
| values are set properly before issuing the G command, if not using =address.
| |
|
| |
| OPTION 2
| |
|
| |
| This option performs the same function as Option 1 but, in addition, allows
| |
| breakpoints to be set at the specified addresses. For example:
| |
|
| |
| G [=address] address
| |
| [address...]
| |
|
| |
| This method causes execution to stop at a specified location so the system or
| |
| program environment can be examined.
| |
|
| |
| You can specify up to ten breakpoints in any order. You may wish to take
| |
| advantage of this if your program has many paths, and you want to stop the
| |
| execution no matter which path the program takes.
| |
|
| |
| The DEBUG program replaces the instruction codes at the breakpoint addresses
| |
| with an interrupt code (hex CC). If any one breakpoint is reached during
| |
| execution, the execution is stopped, the registers and flags are displayed,
| |
| and all the breakpoint addresses are restored to their original instruction
| |
| codes. If no breakpoint is reached, the instructions are not restored.
| |
|
| |
| NOTES:
| |
|
| |
| 1. Once a program has reached completion (DEBUG has displayed the "Program
| |
| terminated normally" message), you must reload the program before it can
| |
| be executed again.
| |
|
| |
| 2. Make sure that the address parameters refer to locations that contain
| |
| valid 8086/8088 instruction codes. If you specify an address that does
| |
| not contain valid instruction in the first byte, unpredictable results
| |
| occur.
| |
|
| |
| 3. The stack pointer must be valid and have 6 bytes available for the Go
| |
| command, otherwise, unpredictable results occur.
| |
|
| |
| 4. If only an offset is entered for a breakpoint, the G command assumes the
| |
| segment contained in the CS register.
| |
|
| |
| 5. Do not set breakpoints at instructions in read-only memory (ROM BIOS or
| |
| ROM BASIC).
| |
|
| |
| For example:
| |
|
| |
| G 102 1EF 208
| |
|
| |
| Be careful not to set a breakpoint between a segment override indication
| |
| (such as ES; alone on a line), and the instruction that the override
| |
| qualifies.
| |
|
| |
| Execution begins with the current instruction, whose address is the current
| |
| values of CS:IP. The =address parameter was not used.
| |
|
| |
| Three breakpoints are specified; assume that the second is reached.
| |
| Execution stops before the instruction at location CS:1EF is executed, the
| |
| original instruction codes are restored, all three breakpoints are removed,
| |
| the display occurs, and the Go command ends.
| |
|
| |
| Refer to the Register command for a description of the display.
| |
|
| |
| H (HEXARITHMETIC) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Adds the two hexadecimal values, then subtracts the second from the first.
| |
| Displays the sum and difference on one line.
| |
|
| |
| FORMAT
| |
|
| |
| H value value
| |
|
| |
| EXAMPLE
| |
|
| |
| H 0F 8
| |
| 0017 0007
| |
|
| |
| The hexadecimal sum of 000F and 0008 is 0017, and their difference is 0007.
| |
|
| |
| I (INPUT) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Inputs and displays (in hexadecimal) 1 byte from the specified port.
| |
|
| |
| FORMAT
| |
|
| |
| I portaddress
| |
|
| |
| PARAMETERS
| |
|
| |
| portaddress A 1-4 character hexadecimal value specifying an 8- or 16-bit port
| |
| address.
| |
|
| |
| EXAMPLE
| |
|
| |
| I 2F8
| |
| 6B
| |
|
| |
| The single hexadecimal byte read from port 02F8 is displayed (6B).
| |
|
| |
| L (LOAD) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Loads a file or absolute disk sectors into memory.
| |
|
| |
| FORMAT
| |
|
| |
| L [address[drive sector sector]]
| |
|
| |
| PARAMETERS
| |
|
| |
| address Any of the following formats:
| |
|
| |
| A segment register plus an offset, such as CS:0100.
| |
| A segment address plus an offset, such as 4BA:0100.
| |
| An offset only, such as 100. In this case, the default
| |
| segment is used.
| |
|
| |
| drive A decimal number that indicates a particular drive. For example,
| |
| drive A is 0, drive B is 1, and so on.
| |
|
| |
| sector 1-3 character hexadecimal values that specify the starting
| |
| relative sector number and the number of sectors to be loaded or
| |
| written.
| |
|
| |
| NOTE: Relative sector numbers are obtained by counting the
| |
| sectors on the disk surface. The first sector on the disk
| |
| is at track 0, sector 1, head 0, and is relative sector 0.
| |
| The numbering continues for each sector on that track and
| |
| head, then continues with the first sector on the next
| |
| head of the same track. When all sectors on all heads of
| |
| the track have been counted, numbering continues with the
| |
| first sector on head 0 of the next track.
| |
|
| |
| COMMENTS
| |
|
| |
| The maximum number of sectors that can be loaded with a single Load command
| |
| is hex 80. A sector contains 512 bytes.
| |
|
| |
| NOTE: DEBUG displays a message if a disk read error occurs. You can retry
| |
| the read operation by pressing the F3 key to re-display the Load
| |
| command. Then press the Enter key.
| |
|
| |
| The Load command has two format options.
| |
|
| |
| OPTION 1
| |
|
| |
| Use this option to load data from the disk specified by drive and place the
| |
| data in memory beginning at the specified address. For example:
| |
|
| |
| L address drive sector sector
| |
|
| |
| The data is read from the specified starting relative sector (first sector)
| |
| and continues until the requested number of sectors is read (second sector).
| |
|
| |
| NOTE: If you only enter an offset for the beginning address, the L command
| |
| assumes the segment contained in the CS register.
| |
|
| |
| For example, to load data, you might enter:
| |
|
| |
| L DS:100 1 0F 6D
| |
|
| |
| The data is loaded from the diskette in drive B and placed in memory
| |
| beginning at DS:100. Consecutive sectors of data are transferred, 6DH (109),
| |
| starting with relative sector hex 0F (15) (the 16th sector on the diskette).
| |
|
| |
| NOTE: Option 1 cannot be used if the drive specified is a network drive.
| |
|
| |
| OPTION 2
| |
|
| |
| When issued without parameters, or with only the address parameter, use this
| |
| option to load the file whose file specification is at CS:80. For example:
| |
|
| |
| L
| |
|
| |
| or
| |
|
| |
| L address
| |
|
| |
| This condition is met by specifying the file name when starting the DEBUG
| |
| program, or by using the Name command.
| |
|
| |
| NOTE: If DEBUG was started with a file specification and subsequent Name
| |
| commands were used, you may need to enter a new Name command for the
| |
| proper file specification before issuing the Load command.
| |
|
| |
| The file is loaded into memory beginning at CS:100 (or the location specified
| |
| by address), and is read from the drive specified in the file specification,
| |
| or from the default drive, if none was specified. Note that files with
| |
| extensions of .COM or .EXE are always loaded at CS:100. If you specified an
| |
| address, it is ignored.
| |
|
| |
| The BX and CX registers are set to the number of bytes read; however, if the
| |
| file being loaded has an extension of .EXE, the BX and CX registers are set
| |
| to the actual program size. The file may be loaded at the high end of
| |
| memory. Refer to "The DEBUG Work Space" on page 10-3 for the conditions that
| |
| are in effect when .EXE or .HEX files are loaded.
| |
|
| |
| For example:
| |
|
| |
| DEBUG
| |
| -N myprog
| |
| -L
| |
|
| |
| The file named MYPROG is loaded from the default directory and placed in
| |
| memory beginning at location CS:0100.
| |
|
| |
| M (MOVE) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Moves the contents of the memory locations specified by range to the
| |
| locations beginning at the address specified.
| |
|
| |
| FORMAT
| |
|
| |
| M range address
| |
|
| |
| PARAMETERS
| |
|
| |
| range Either of these two formats:
| |
|
| |
| An address followed by an offset, such as CS:100 110.
| |
| An address followed by L value, where value is the number of
| |
| hexadecimal bytes to be processed. For example, CS:100 L 10.
| |
|
| |
| The limit for range is hexadecimal 10000 or decimal 64KB. To
| |
| specify a range of 64KB within 4 hexadecimal characters, enter
| |
| 0000 or 0 for value.
| |
|
| |
| address Any of the following formats:
| |
|
| |
| A segment register plus an offset, such as CS:0100.
| |
| A segment address plus an offset, such as 4BA:0100.
| |
| An offset only, such as 100. In this case, the default
| |
| segment is used.
| |
|
| |
| COMMENTS
| |
|
| |
| Overlapping moves are always performed without loss of data during the
| |
| transfer. (The source and destination areas share some of the same memory
| |
| locations.)
| |
|
| |
| The data in the source area remains unchanged unless overwritten by the move.
| |
|
| |
| NOTES:
| |
|
| |
| 1. If you enter only an offset for the beginning address of the range, the M
| |
| command assumes the segment contained in the DS register. If you specify
| |
| an ending address for the range, enter it with only an offset value.
| |
|
| |
| 2. If you enter only an offset for the address of the destination area, the
| |
| M command assumes the segment contained in the DS register.
| |
|
| |
| EXAMPLE
| |
|
| |
| M CS:100 L10 500
| |
|
| |
| The 17 bytes of data from CS:100 through CS:110 are moved to the area of
| |
| memory beginning at DS:500.
| |
|
| |
| N (NAME) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Formats file control blocks for the first two file specifications, at
| |
| CS:5C and CS:6C. (Starting DEBUG with a file specification also formats
| |
| a file control block at CS:5C.)
| |
|
| |
| The file control blocks are set up for the Load and Write commands and to
| |
| supply required file names for the program being debugged.
| |
|
| |
| All file specifications and other parameters, including delimiters, are
| |
| placed exactly as entered in a parameter save area at CS:81, with CS:80
| |
| containing the number of characters entered. Register AX is set to
| |
| indicate the validity of the drive specifiers entered with the first two
| |
| file specifications.
| |
|
| |
| FORMAT
| |
|
| |
| N [d:][path]filename[.ext]
| |
|
| |
| COMMENTS
| |
|
| |
| If you start the DEBUG program without a file specification, you must use the
| |
| Name command before a file can be loaded with the L command.
| |
|
| |
| EXAMPLE
| |
|
| |
| DEBUG
| |
| -N myprog
| |
| -L
| |
|
| |
| To define file specifications or other parameters required by the program
| |
| being debugged, enter:
| |
|
| |
| DEBUG myprog
| |
| -N file1 file2
| |
|
| |
| In this example, DEBUG loads the file MYPROG at CS:100, and leaves the file
| |
| control block at CS:5C formatted with the same file specification. Then, the
| |
| Name command formats file control blocks for file1 and file2 at CS:5C and
| |
| CS:6C, respectively. The file control block for MYPROG is overwritten. The
| |
| parameter area at CS:81 contains all characters entered after the N,
| |
| including all delimiters, and CS:80 contains the count of those characters
| |
| (hex 0C).
| |
|
| |
| O (OUTPUT) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Sends the byte to the specified output port.
| |
|
| |
| FORMAT
| |
|
| |
| O portaddress byte
| |
|
| |
| PARAMETERS
| |
|
| |
| portaddress A 1-4 character hexadecimal value specifying an 8- or 16-bit port
| |
| address.
| |
|
| |
| EXAMPLE
| |
|
| |
| To send the byte value 4F to output port 2F8, enter:
| |
|
| |
| O 2F8 4F
| |
|
| |
| P (PROCEED) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Causes the execution of a subroutine call, a loop instruction, an interrupt,
| |
| or a repeat string instruction to stop at the next instruction.
| |
|
| |
| FORMAT
| |
|
| |
| P[=address][value]
| |
|
| |
| PARAMETERS
| |
|
| |
| address Any of the following formats:
| |
|
| |
| A segment register plus an offset, such as CS:0100.
| |
| A segment address plus an offset, such as 4BA:0100.
| |
| An offset only, such as 100. In this case, the default
| |
| segment is used.
| |
|
| |
| value A 1-4 character hexadecimal value, specifying the number of
| |
| instructions to execute.
| |
|
| |
| COMMENTS
| |
|
| |
| When at a subroutine call, a loop instruction, an interrupt, or a repeat
| |
| string instruction, issue the Proceed command to execute the instruction
| |
| (perform the entire function), and return control at the next instruction.
| |
| The Proceed command has the same syntax as the Trace command. Specifying P0
| |
| is the same as specifying T0.
| |
|
| |
| EXAMPLE
| |
|
| |
| If the following instructions are executed:
| |
|
| |
| 0100 CALL 1000
| |
| 0103 JC 2000
| |
| .
| |
| .
| |
| .
| |
| 1000 XOR AX,AX
| |
| .
| |
| .
| |
| .
| |
| 1XXX RET
| |
|
| |
| And if CS:IP was pointing to the CALL 1000 instruction, typing P causes the
| |
| execution of the subroutine and returns control to DEBUG at the JC
| |
| instruction.
| |
|
| |
| Q (QUIT) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Ends the DEBUG program.
| |
|
| |
| FORMAT
| |
|
| |
| Q
| |
|
| |
| COMMENTS
| |
|
| |
| The file that you are working on in memory is not saved by the Quit command.
| |
| You must use the Write command to save the file.
| |
|
| |
| DEBUG returns to the command processor which then issues the normal command
| |
| prompt.
| |
|
| |
| EXAMPLE
| |
|
| |
| -Q
| |
| A>
| |
|
| |
| R (REGISTER) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| The Register command has the following three functions:
| |
|
| |
| Displays the hexadecimal contents of a single register with the option of
| |
| changing those contents
| |
|
| |
| Displays the hexadecimal contents of all the registers, plus the
| |
| alphabetic flag settings, and the next instruction to be executed
| |
|
| |
| Displays the eight 2-letter alphabetic flag settings with the option of
| |
| changing any or all of them.
| |
|
| |
| FORMAT
| |
|
| |
| R [registername]
| |
|
| |
| PARAMETERS
| |
|
| |
| registername The valid names are:
| |
|
| |
| AX SP CS IP
| |
| BX BP DS F
| |
| CX SI ES
| |
| DX DI SS
| |
|
| |
| IP refers to the instruction pointer, and F refers to the flags
| |
| register.
| |
|
| |
| COMMENTS
| |
|
| |
| When the DEBUG program starts, the registers and flags are set to certain
| |
| values for the program being debugged. (Refer to "The DEBUG Work Space" on
| |
| page 10-3.)
| |
|
| |
| DISPLAY A SINGLE REGISTER
| |
|
| |
| To display the contents of a single register, enter the register name:
| |
|
| |
| R AX
| |
|
| |
| The system might respond with:
| |
|
| |
| AX F1E4
| |
| :
| |
|
| |
| Now you can take one of two actions: press the Enter key to leave the
| |
| contents unchanged, or change the contents of the AX register by entering a
| |
| 1-4 character hexadecimal value, such as hex FFF.
| |
|
| |
| AX F1E4
| |
| :FFF
| |
|
| |
| Now, pressing the Enter key changes the contents of the AX register to hex
| |
| 0FFF.
| |
|
| |
| DISPLAY ALL REGISTERS AND FLAGS
| |
|
| |
| To display the contents of all registers and flags and the next instruction
| |
| to be executed, type:
| |
|
| |
| R
| |
|
| |
| The system responds:
| |
|
| |
| AX=0E00 BX=00FF CX=0007 DX=01FF SP=039D BP=0000 SI=005C DI=0000
| |
| DS=3D5B ES=3D5B SS=3D5B CS=3D5B IP=011A NV UP EI PL NZ NA PO NC
| |
| 3D5B:011A CD21 INT 21
| |
|
| |
| The first four lines display the hexadecimal contents of the registers and
| |
| the eight alphabetic flag settings. The last line indicates the location of
| |
| the next instruction to be executed and its hexadecimal and unassembled
| |
| formats. This is the instruction pointed to by CS:IP.
| |
|
| |
| A system with an 80-column display shows:
| |
|
| |
| 1st line - 8 registers
| |
| 2nd line - 5 registers and 8 flag settings
| |
| 3rd line - next instruction information
| |
|
| |
| A system with a 40-column display shows:
| |
|
| |
| 1st line - 4 registers
| |
| 2nd line - 4 registers
| |
| 3rd line - 4 registers
| |
| 4th line - 1 register and 8 flag settings
| |
| 5th line - next instruction information
| |
|
| |
| Display All Flags
| |
|
| |
| There are eight flags, each with two-letter codes to indicate either a set
| |
| condition or a clear condition. The flags appear in displays in the order
| |
| shown in the following table:
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FLAG NAME SET CLEAR |
| |
| +---------------------------------------------------------------------------+
| |
| | Overflow (yes/no) OV NV |
| |
| +---------------------------------------------------------------------------+
| |
| | Direction (decrease/increase) DN UP |
| |
| +---------------------------------------------------------------------------+
| |
| | Interrupt (enable/disable) EI DI |
| |
| +---------------------------------------------------------------------------+
| |
| | Sign (negative/positive) NG PL |
| |
| +---------------------------------------------------------------------------+
| |
| | Zero (yes/no) ZR NZ |
| |
| +---------------------------------------------------------------------------+
| |
| | Auxiliary carry (yes/no) AC NA |
| |
| +---------------------------------------------------------------------------+
| |
| | Parity (even/odd) PE PO |
| |
| +---------------------------------------------------------------------------+
| |
| | Carry (yes/no) CY NC |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| To display all flags, enter:
| |
|
| |
| R F
| |
|
| |
| If all the flags are in a set condition, the response is:
| |
|
| |
| OV DN EI NG ZR AC PE CY -
| |
|
| |
| Now you can either press the Enter key to leave the settings unchanged or
| |
| change any or all of the settings.
| |
|
| |
| To change a flag, just enter its opposite code. The opposite codes can be
| |
| entered in any order with or without intervening spaces. For example, to
| |
| change the first, third, fifth, and seventh flags, enter:
| |
|
| |
| OV DN EI NG ZR AC PE CY - PONZDINV
| |
|
| |
| The changes in this example are entered in reverse order.
| |
|
| |
| Press the Enter key and the flags are modified as specified, the prompt
| |
| appears, and you can enter the next command.
| |
|
| |
| If you want to see if the new codes are in effect, enter:
| |
|
| |
| R F
| |
|
| |
| The response is:
| |
|
| |
| NV DN DI NG NZ AC PO CY -
| |
|
| |
| The first, third, fifth, and seventh flags are changed as requested. The
| |
| second, fourth, sixth, and eighth flags are unchanged. A single flag can be
| |
| changed only once for each R F command.
| |
|
| |
| S (SEARCH) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Searches the range for the character(s) in the list.
| |
|
| |
| FORMAT
| |
|
| |
| S range list
| |
|
| |
| range Either of these two formats:
| |
|
| |
| An address followed by an offset, such as CS:100 110.
| |
| An address followed by L value, where value is the number of
| |
| hexadecimal bytes to be processed. For example, CS:100 L 10.
| |
|
| |
| The limit for range is hexadecimal 10000 or decimal 64KB. To
| |
| specify a range of 64KB within 4 hexadecimal characters, enter
| |
| 0000 or 0 for value.
| |
|
| |
| list A string of byte values. If you include a character string,
| |
| enclose the characters in single or double quotation marks. To
| |
| specify a quotation mark as a character within the string when it
| |
| is also used to delimit the string, type it twice.
| |
|
| |
| 'These ''quotes'' are correct.'
| |
| 'This one''s okay, too.'
| |
|
| |
| COMMENTS
| |
|
| |
| All matches are indicated by displaying the addresses where matches are
| |
| found.
| |
|
| |
| A display of the prompt without an address means that no match was found.
| |
|
| |
| NOTE: If you enter only an offset for the starting address of the range, the
| |
| S command assumes the segment contained in the DS register.
| |
|
| |
| EXAMPLE
| |
|
| |
| If you want to search the range of addresses from CS:100 through CS:110 for
| |
| hex 41, type:
| |
|
| |
| S CS:100 110 41
| |
|
| |
| If two matches are found the response might be:
| |
|
| |
| 04BA:0104
| |
| 04BA:010D
| |
|
| |
| If you want to search the same range of addresses for a match with the 4-byte
| |
| list (41 'AB' E), enter:
| |
|
| |
| S CS:100 L 11 41 'AB' E
| |
|
| |
| The starting addresses of all matches are listed. If no match is found, no
| |
| address is displayed.
| |
|
| |
| T (TRACE) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Executes one or more instructions starting with the instruction at CS:IP, or
| |
| at =address, if it is specified. The = must be entered. One instruction is
| |
| assumed, but you can specify more than one with value. This command displays
| |
| the contents of all registers and flags after each instruction executes. For
| |
| a description of the display format, refer to the Register command.
| |
|
| |
| FORMAT
| |
|
| |
| T [=address][value]
| |
|
| |
| PARAMETERS
| |
|
| |
| address Any of the following formats:
| |
|
| |
| A segment register plus an offset, such as CS:0100.
| |
| A segment address plus an offset, such as 4BA:0100.
| |
| An offset only, such as 100. In this case, the default
| |
| segment is used.
| |
|
| |
| value A 1-4 character hexadecimal value, specifying the number of
| |
| instructions to execute.
| |
|
| |
| COMMENTS
| |
|
| |
| The display caused by the Trace command continues until value instructions
| |
| are executed. Therefore, when tracing multiple instructions, remember you
| |
| can suspend the scrolling at any time by pressing the Ctrl and the NumLock
| |
| keys together, or the Pause key. Resume scrolling by entering any other
| |
| character.
| |
|
| |
| NOTES:
| |
|
| |
| 1. The Trace command disables all hardware interrupts before executing the
| |
| user instruction, and then re-enables the interrupts when the trap
| |
| interrupt occurs following the execution of the instruction.
| |
|
| |
| 2. TRACE should not be used with any steps that change the contents of the
| |
| 8259 interrupt mask (ports 20 and 21).
| |
|
| |
| 3. If you trace an INT3 instruction, the breakpoint is set at the INT3
| |
| location.
| |
|
| |
| EXAMPLE
| |
|
| |
| T
| |
|
| |
| If the IP register contains 011A, and that location contains B40E (MOV
| |
| AH,0EH), this may be displayed:
| |
|
| |
| AX=0E00 BX=00FF CX=0007 DX=01FF SP=039D BP=0000 SI=005C DI=0000
| |
| DS=3D5B ES=3D5B SS=3D5B CS=3D5B IP=011C NV UP EI PL NZ NA PO NC
| |
| 3D5B:011C CD21 INT 21
| |
|
| |
| This displays the results after the instruction at 011A is executed, and
| |
| indicates the next instruction to be executed is the INT 21 at location
| |
| 04BA:011C.
| |
|
| |
| T 10
| |
|
| |
| Sixteen instructions are executed (starting at CS:IP). The contents of all
| |
| registers and flags are displayed after each instruction. The display stops
| |
| after the 16th instruction has been executed. Displays may scroll off the
| |
| screen unless you suspend the display by simultaneously pressing the Ctrl and
| |
| NumLock keys, or the Pause key.
| |
|
| |
| U (UNASSEMBLE) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Unassembles instructions (that is, translates the contents of memory into
| |
| assembler-like statements) and displays their addresses and hexadecimal
| |
| values, together with assembler-like statements. For example, a display
| |
| might look like this:
| |
|
| |
| 04BA:0100 206472 AND [SI+72],AH
| |
| 04BA:0103 FC CLD
| |
| 04BA:0104 7665 JBE 016B
| |
|
| |
| FORMAT
| |
|
| |
| U [address]
| |
|
| |
| or
| |
|
| |
| U [range]
| |
|
| |
| PARAMETERS
| |
|
| |
| address Any of the following formats:
| |
|
| |
| A segment register plus an offset, such as CS:0100.
| |
| A segment address plus an offset, such as 4BA:0100.
| |
| An offset only, such as 100. In this case, the default
| |
| segment is used.
| |
|
| |
| range Either of these two formats:
| |
|
| |
| An address followed by an offset, such as CS:100 110.
| |
| An address followed by L value, where value is the number of
| |
| hexadecimal bytes to be processed. For example, CS:100 L 10.
| |
|
| |
| The limit for range is hexadecimal 10000 or decimal 64KB. To
| |
| specify a range of 64KB within 4 hexadecimal characters, enter
| |
| 0000 or 0 for value.
| |
|
| |
| COMMENTS
| |
|
| |
| The number of bytes to be unassembled depends on your system display format
| |
| (40 or 80 columns), and which option you use with the Unassemble command.
| |
|
| |
| NOTES:
| |
|
| |
| 1. In all cases, the number of bytes unassembled and displayed may be
| |
| slightly more than either the amount requested or the default amount.
| |
| This happens because the length of the instructions vary. Therefore,
| |
| unassembling the last instruction may result in more bytes than expected.
| |
|
| |
| 2. Make sure that the address parameters refer to locations containing valid
| |
| 8086/8088 instruction codes. If you specify an address that does not
| |
| contain the first byte of a valid instruction, the display will be
| |
| incorrect.
| |
|
| |
| 3. If you enter only an offset for the starting address, the U command
| |
| assumes the segment contained in the CS register.
| |
|
| |
| The Unassemble command has the following two format options:
| |
|
| |
| OPTION 1
| |
|
| |
| Use this option to either unassemble instructions without specifying an
| |
| address, or to unassemble instructions beginning with a specified address.
| |
| For example:
| |
|
| |
| U
| |
|
| |
| or
| |
|
| |
| U address
| |
|
| |
| Sixteen bytes are unassembled with a 40-column display. Thirty-two bytes are
| |
| unassembled in 80-column mode.
| |
|
| |
| Instructions are unassembled beginning with the specified address.
| |
|
| |
| If you do not specify an address, the U command assumes the starting address
| |
| is the location following the last instruction unassembled by a previous U
| |
| command. Thus, it is possible to unassemble consecutive locations, producing
| |
| continuous unassembled displays, by entering consecutive U commands without
| |
| parameters.
| |
|
| |
| If no previous U command is entered, the location is offset hex 0100 into the
| |
| segment originally initialized in the segment registers by DEBUG.
| |
|
| |
| OPTION 2
| |
|
| |
| Use this option to unassemble instructions in a specified address range. For
| |
| example:
| |
|
| |
| U range
| |
|
| |
| All instructions in the specified address range are unassembled, regardless
| |
| of the system display format.
| |
|
| |
| NOTE: If you specify an ending address, enter it with only an offset value.
| |
|
| |
| For example:
| |
|
| |
| U 04ba:0100 108
| |
|
| |
| The display response may be:
| |
|
| |
| 04BA:0100 206472 AND [SI+72],AH
| |
| 04BA:0103 FC CLD
| |
| 04BA:0104 7665 JBE 016B
| |
| 04BA:0106 207370 AND [BP+DI+70],DH
| |
|
| |
| The same display appears if you enter:
| |
|
| |
| U 04BA:100 L 7
| |
|
| |
| or
| |
|
| |
| U 04BA:100 L 8
| |
|
| |
| or
| |
|
| |
| U 04BA:100 L 9
| |
|
| |
| W (WRITE) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Writes the data being debugged to disk.
| |
|
| |
| FORMAT
| |
|
| |
| W [address [drive sector sector]]
| |
|
| |
| PARAMETERS
| |
|
| |
| address Any of the following formats:
| |
|
| |
| A segment register plus an offset, such as CS:0100.
| |
| A segment address plus an offset, such as 4BA:0100.
| |
| An offset only, such as 100. In this case, the default
| |
| segment is used.
| |
|
| |
| drive A decimal number that indicates a particular drive. For example,
| |
| drive A is 0, drive B is 1, and so on.
| |
|
| |
| sector 1-3 character hexadecimal values that specify the starting
| |
| relative sector number and the number of sectors to be loaded or
| |
| written.
| |
|
| |
| NOTE: Relative sector numbers are obtained by counting the
| |
| sectors on the disk surface. The first sector on the disk
| |
| is at track 0, sector 1, head 0, and is relative sector 0.
| |
| The numbering continues for each sector on that track and
| |
| head, then continues with the first sector on the next
| |
| head of the same track. When all sectors on all heads of
| |
| the track have been counted, numbering continues with the
| |
| first sector on head 0 of the next track.
| |
|
| |
| COMMENTS
| |
|
| |
| No more than hex 80 sectors can be written with a single Write command. A
| |
| sector contains 512 bytes.
| |
|
| |
| DEBUG displays a message if a disk write error occurs. You can retry the
| |
| write operation by pressing the F3 key to re-display the Write command, then
| |
| press the Enter key.
| |
|
| |
| The Write command has two format options.
| |
|
| |
| OPTION 1
| |
|
| |
| Use this option to write data to disk beginning at a specified address. For
| |
| example:
| |
|
| |
| W address drive sector sector
| |
|
| |
| The data beginning at the specified address is written to the disk in the
| |
| indicated drive. The data is written starting at the specified starting
| |
| relative sector (first sector) and continues until the requested number of
| |
| sectors are filled (second sector).
| |
|
| |
| NOTES:
| |
|
| |
| 1. Be extremely careful when you write data to absolute sectors because an
| |
| erroneous sector specification destroys whatever was on the disk at that
| |
| location.
| |
|
| |
| 2. If only an offset is entered for the beginning address, the W command
| |
| assumes the segment is contained in the CS register.
| |
|
| |
| 3. Remember, the starting sector and the sector count are both specified in
| |
| hexadecimal.
| |
|
| |
| 4. Option 1 cannot be used if the specified drive is a network drive.
| |
|
| |
| For example:
| |
|
| |
| W 1FD 1 100 A
| |
|
| |
| The data beginning at CS:01FD is written to the diskette in drive B, starting
| |
| at relative sector hex 100 (256) and continuing for hex 0A (10) sectors.
| |
|
| |
| OPTION 2
| |
|
| |
| This option permits you to use the WRITE command without specifying
| |
| parameters or specifying only the address parameter. For example:
| |
|
| |
| W
| |
|
| |
| or
| |
|
| |
| W address
| |
|
| |
| When issued as shown above, the Write command writes the file (whose file
| |
| specification is at CS:80) to disk.
| |
|
| |
| This condition is met by specifying the file when starting the DEBUG program,
| |
| or by using the Name command.
| |
|
| |
| NOTE: If DEBUG was started with a file specification and subsequent Name
| |
| commands were used, you may need to enter a new Name command for the
| |
| proper file specification before issuing the Write command.
| |
|
| |
| In addition, the BX and CX registers must be set to the number of bytes to be
| |
| written. They may have been set properly by the DEBUG or Load commands, but
| |
| were changed by a Go or Trace command. You must be certain the BX and CX
| |
| registers contain the correct values.
| |
|
| |
| The file beginning at CS:100, or at the location specified by address, is
| |
| written to the diskette in the drive included in the file specification or
| |
| the default drive if no drive was specified.
| |
|
| |
| The debugged file is written over the original file that was loaded into
| |
| memory, or into a new file if the file name in the FCB didn't previously
| |
| exist.
| |
|
| |
| NOTE: An error message is issued if you try to write a file with an
| |
| extension of .EXE or .HEX. These files are written in a specific
| |
| format that DEBUG cannot support.
| |
|
| |
| If you find it necessary to modify a file with an extension of .EXE or .HEX,
| |
| and the exact locations to be modified are known, use the following
| |
| procedure:
| |
|
| |
| 1. RENAME the file to an extension other than .EXE or .HEX.
| |
|
| |
| 2. Load the file into memory using the DEBUG or Load command.
| |
|
| |
| 3. Modify the file as needed in memory, but do not try to execute it with
| |
| the Go or Trace commands. Unpredictable results would occur.
| |
|
| |
| 4. Write the file back using the Write command.
| |
|
| |
| 5. RENAME the file to its correct name.
| |
|
| |
| XA (EMS ALLOCATE) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Allocates a specified number of expanded memory pages to a handle.
| |
|
| |
| FORMAT
| |
|
| |
| XA count
| |
|
| |
| COMMENTS
| |
|
| |
| The count indicates the number of 16K pages to allocate. If the amount of
| |
| expanded memory identified by count is available, a message is displayed,
| |
| indicating that a handle has been created. The XS (EMS Status) command can
| |
| be used to display the number of expanded memory pages that are available.
| |
|
| |
| EXAMPLE
| |
|
| |
| To allocate two EMS pages, enter:
| |
|
| |
| XA 2
| |
|
| |
| If two pages of memory are available, a message like this is displayed:
| |
|
| |
| Handle created = 000E
| |
|
| |
| XD (EMS DEALLOCATE) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Deallocates a handle.
| |
|
| |
| FORMAT
| |
|
| |
| XD handle
| |
|
| |
| COMMENTS
| |
|
| |
| The handle identifies the number of the handle to be deallocated. If the
| |
| number is valid, a message is displayed, indicating the handle has been
| |
| deallocated. The XS (EMS Status) command can be used to display the handles
| |
| currently being used.
| |
|
| |
| EXAMPLE
| |
|
| |
| To deallocate a handle when you have only one allocated, you can enter:
| |
|
| |
| XD 000E
| |
|
| |
| If the handle deallocation is successful, you receive a message like this:
| |
|
| |
| Handle 000E deallocated.
| |
|
| |
| XM (EMS MAP) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Maps an EMS logical page to an EMS physical page from an EMS handle.
| |
|
| |
| FORMAT
| |
|
| |
| XM lpage ppage handle
| |
|
| |
| COMMENTS
| |
|
| |
| The lpage specifies the number of the handle's logical page that is to be
| |
| mapped. The ppage is the number of the physical page to be mapped to. The
| |
| handle is the EMS allocated label used to reference a group of logical pages.
| |
| If syntax items are valid, a message is displayed indicating that the logical
| |
| page has been mapped to the physical page.
| |
|
| |
| EXAMPLE
| |
|
| |
| To map a logical page to a physical page using handle 0001, you can enter:
| |
|
| |
| XM 1 0 1
| |
|
| |
| If the mapping is successful, you receive this message:
| |
|
| |
| Logical page 01 mapped to physical page 00.
| |
|
| |
| XS (EMS STATUS) COMMAND
| |
|
| |
| PURPOSE
| |
|
| |
| Displays the status of expanded memory.
| |
|
| |
| FORMAT
| |
|
| |
| XS
| |
|
| |
| COMMENTS
| |
|
| |
| The following expanded memory information is displayed:
| |
|
| |
| Handle %1 has %2 pages allocated
| |
|
| |
| .
| |
| .
| |
| .
| |
| Physical page %1 = Frame segment %2
| |
|
| |
| .
| |
| .
| |
| .
| |
| %1 of a total %2 EMS pages have been allocated
| |
| %1 of a total %2 EMS handles have been allocated
| |
|
| |
| EXAMPLE
| |
|
| |
| A line is displayed for each handle allocated with its associated logical
| |
| page count.
| |
|
| |
| DEBUG ERROR MESSAGES
| |
|
| |
| The following error messages are produced by the DEBUG utility:
| |
|
| |
| ACCESS DENIED The result of attempting to Write (W) to a
| |
| read-only file.
| |
|
| |
| DISK ERROR READING DRIVE %1 An invalid parameter was entered on the
| |
| Load (L) command or an error occurred on
| |
| issuing the Load (L) command.
| |
|
| |
| DISK ERROR WRITING DRIVE %1 An invalid parameter was entered on the
| |
| Write (W) command or an error occurred on
| |
| issuing the Write (W) command.
| |
|
| |
| EMS HARDWARE/SOFTWARE FAILURE The result of an EMS command. Tells the
| |
| user EMS is not functioning properly.
| |
|
| |
| EMS NOT INSTALLED The result of an EMS command. Tells user
| |
| EMS is not installed.
| |
|
| |
| &HAT. ERROR Points to the offending operand in an error
| |
| condition.
| |
|
| |
| ERROR IN EXE OR HEX FILE The EXE or HEX file are in error.
| |
|
| |
| EXE AND HEX FILES CANNOT BE WRITTEN A file in EXE or HEX format cannot be
| |
| written to a disk.
| |
|
| |
| EXEC FAILURE The execution of the requested file failed.
| |
|
| |
| FILE CREATION ERROR The result of attempting to Write (W) to a
| |
| system or hidden file.
| |
|
| |
| FILE NOT FOUND Issued from the Load (L) command when a
| |
| file is not found for loading.
| |
|
| |
| FREE PAGES EXCEEDED The result of an EMS command. Tells the
| |
| user that the request has exceeded the
| |
| amount of free EMS pages available.
| |
|
| |
| HANDLE NOT FOUND The result of an EMS command. Tells the
| |
| user an EMS handle was not found.
| |
|
| |
| INCORRECT DOS VERSION Incorrect version of DEBUG for the DOS
| |
| version running.
| |
|
| |
| INSUFFICIENT MEMORY Not enough memory to Load (L) the specified
| |
| file.
| |
|
| |
| INSUFFICIENT SPACE ON DISK Out of disk space for a Write (W) command.
| |
|
| |
| INVALID DRIVE SPECIFICATION The drive referenced by the Name (N) and
| |
| Load (L) command is invalid; that is, it
| |
| does not exist.
| |
|
| |
| LOGICAL PAGE OUT OF RANGE The result of an EMS command. Tells the
| |
| user that the logical page requested is not
| |
| in the range of possible pages.
| |
|
| |
| MISSING OR INVALID EMS PARAMETER The result of an EMS command. Tells the
| |
| user a missing or invalid parameter was
| |
| entered.
| |
|
| |
| NO FREE HANDLES The result of an EMS command. Tells the
| |
| user that there are no more EMS handles
| |
| available for allocation.
| |
|
| |
| PARAMETER ERROR The result of an EMS command. Tells the
| |
| user that an EMS parameter is in error.
| |
|
| |
| PHYSICAL PAGE OUT OF RANGE The result of an EMS command. Tells the
| |
| user that the physical page requested is
| |
| not in the range of possible pages.
| |
|
| |
| PROGRAM TERMINATED NORMALLY An Interrupt 20H has been encountered,
| |
| signalling program termination.
| |
|
| |
| TOTAL PAGES EXCEEDED The result of an EMS command. Tells the
| |
| user that the total EMS pages have been
| |
| exceeded.
| |
|
| |
| WRITE (W) ERROR, NO DESTINATION DEFINED Attempt to Write (W) to a file that
| |
| has not yet been Named (N).
| |
|
| |
| WRITE PROTECT ERROR WRITING DRIVE %1 A Write (W) to a write-protected disk
| |
| caused an error.
| |
|
| |
| WRITING %1 BYTES Reports the number of bytes written to a
| |
| file when the Write (W) command is issued.
| |
| </PRE>
| |
| | |
| ==Chapter 11==
| |
| <PRE>
| |
| CHAPTER 11. WRITING AN INSTALLABLE DEVICE DRIVER 26
| |
| Types of Device Drivers 39
| |
| Character Device Drivers 48
| |
| Block Device Drivers 55
| |
| How DOS 4.00 Installs Device Drivers 84
| |
| The Basic Parts of a Device Driver 134
| |
| The Device Driver Header 148
| |
| The Strategy Routine 274
| |
| The Interrupt Routines 283
| |
| How DOS 4.00 Passes a Request 300
| |
| Responding to Requests 392
| |
| Initialization Request 456
| |
| Media Check Request 511
| |
| Build BPB Request 630
| |
| Input and Output Requests 815
| |
| Nondestructive Input No Wait Request 879
| |
| Character Input and Output Status Requests 901
| |
| Character Input and Output Flush Requests 935
| |
| Open and Close Requests 951
| |
| Removable Media Request 983
| |
| Generic IOCTL Request 1008
| |
| Get Logical Device Request 1037
| |
| Set Logical Device Request 1055
| |
| CLOCK$ Device Driver Example 1073
| |
|
| |
| CHAPTER 11. WRITING AN INSTALLABLE DEVICE DRIVER
| |
|
| |
| This chapter provides guide and system architecture information to support
| |
| successful creation of an installable device driver.
| |
|
| |
| We recommend you use the information provided in this chapter in conjunction
| |
| with the information provided in the VDISK.ASM file on the utilities
| |
| diskette. This file contains the fully documented source code for the VDISK
| |
| device driver, which emulates a fixed disk in RAM.
| |
|
| |
| NOTE: The example on the utilities diskette does not reflect the current
| |
| level of VDISK.SYS..
| |
|
| |
| TYPES OF DEVICE DRIVERS
| |
|
| |
| A device driver is a memory image file or an .EXE file that contains the code
| |
| needed to implement a device. DOS 4.00 allows two types of device drivers to
| |
| be installed:
| |
|
| |
| Character device drivers
| |
| Block device drivers.
| |
|
| |
| CHARACTER DEVICE DRIVERS
| |
|
| |
| Character device drivers perform character I/O in a serial manner and have
| |
| names such as CON, AUX, CLOCK$. You can open handles or FCBs to perform
| |
| input and output to character devices. Because character device drivers have
| |
| only one name, they support only one device.
| |
|
| |
| BLOCK DEVICE DRIVERS
| |
|
| |
| Block device drivers are the fixed disk or diskette drives on the system.
| |
| They perform random I/O in pieces called blocks, which are usually the
| |
| physical sector size of the disk. Block devices are not named as character
| |
| devices are and you cannot open them. Instead they are mapped using the
| |
| drive letters such as A, B, and C.
| |
|
| |
| A single block device driver can be responsible for one or more disk or
| |
| diskette drives. For example, the first block device driver in the device
| |
| chain may define four units such as A, B, C, and D. The second device driver
| |
| may define three units: E, F, and G. The limit is 26 devices with the
| |
| letters A through Z assigned to drives. The position of the driver in the
| |
| chain determines the way in which the drive units and drive letters
| |
| correspond.
| |
|
| |
| Support for Media Greater than 32MB
| |
|
| |
| A block device driver that runs in the DOS 4.00 environment can be written to
| |
| process 32-bit sector numbers. This ability provides support for fixed disk
| |
| media greater than 32MB. This support is described in these sections:
| |
|
| |
| "The Device Driver Header" on page 11-3
| |
| "Build BPB Request" on page 11-14
| |
| "Input and Output Requests" on page 11-18.
| |
|
| |
| DOS 4.00 also allows users to install their own device drivers that support
| |
| media greater than 32MB.
| |
|
| |
| HOW DOS 4.00 INSTALLS DEVICE DRIVERS
| |
|
| |
| DOS 4.00 installs device drivers dynamically at startup time by reading and
| |
| processing the DEVICE command in CONFIG.SYS. For example, if you have
| |
| written a device driver called DRIVER1, include the following command in
| |
| CONFIG.SYS:
| |
|
| |
| device=driver1
| |
|
| |
| The DOS 4.00 device interface links device drivers together in a chain,
| |
| permitting you to add device drivers for optional devices.
| |
|
| |
| Each device must be initialized. The device driver's initialization
| |
| interrupt routine is called once when the device is installed. The
| |
| initialization routine returns the location in memory of the ending address
| |
| of the device driver. After setting the ending address field, a character
| |
| device driver sets the status word and returns.
| |
|
| |
| DOS 4.00 processes installed character device drivers before handling default
| |
| devices. To have DOS 4.00 install a new CON device (for example, in the
| |
| device driver header's Name/Unit field) name the device CON and set the
| |
| standard input device and standard output device bits in the attribute field.
| |
| Because DOS 4.00 installs drivers anywhere in memory, care must be taken in
| |
| any references to locations not in the segment. Your driver will not always
| |
| be loaded at the same memory location each time.
| |
|
| |
| Block devices are installed in the same manner as character devices, above.
| |
| Block devices return additional information such as the number of units.
| |
| This number identifies the devices' logical names. For example, if the
| |
| current maximum logical device letter is F at the time of the install call,
| |
| and the block device driver initialization routine returns three logical
| |
| units, the logical names of the devices are G, H, and I. The mapping is
| |
| determined by the position of the driver in the device list and the number of
| |
| units associated with the device. The number of units returned by INIT
| |
| overrides the value in the name/unit field of the device header.
| |
|
| |
| A block device also returns a pointer to a BIOS parameter block (BPB) array.
| |
| This is a pointer to an array of n word pointers, where n is the number of
| |
| units defined. If all the units are the same, the array is able to point to
| |
| the same BIOS parameter block, thus saving space. The array must be
| |
| protected below the ending address pointer set by the return.
| |
|
| |
| The BPB contains information pertinent to the devices such as the sector size
| |
| and the number of sectors per allocation unit. The sector size in the BPB
| |
| cannot be greater than the maximum allowed size set by DOS 4.00
| |
| initialization.
| |
|
| |
| A block device returns the media descriptor byte passed to devices to report
| |
| which parameters DOS 4.00 is using for a particular drive unit.
| |
|
| |
| THE BASIC PARTS OF A DEVICE DRIVER
| |
|
| |
| A device driver is a memory image file or an .EXE file containing the code
| |
| needed to implement a device. All DOS 4.00 installable device drivers have
| |
| these things in common:
| |
|
| |
| A device driver header, which identifies the device to DOS 4.00 and
| |
| defines the strategy and interrupt entry points. Since a device driver
| |
| is simply loaded and does not use a program segment prefix, the device
| |
| header must be located at physical location 0 of the device driver (ORG 0
| |
| or no ORG statement).
| |
| A strategy routine, which saves a pointer to the Request Header.
| |
| The interrupt routines, which perform the requested operation.
| |
|
| |
| THE DEVICE DRIVER HEADER
| |
|
| |
| A device driver requires a device header containing the following:
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Pointer to next device header DWORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Attribute WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Pointer to device strategy routine WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Pointer to device interrupt routine WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Name/unit field 8 BYTES |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| Pointer to Next Device Header
| |
|
| |
| The device driver header is a pointer to the device header of the next device
| |
| driver. It is a doubleword field set by DOS 4.00 at the time the device
| |
| driver is loaded. The first word is an offset and the second word is the
| |
| segment.
| |
|
| |
| If you are loading only one device driver, set the device header field to -1
| |
| before loading the device. If you are loading more than one device driver,
| |
| set the first word of the device header field to the offset of the next
| |
| device driver's header. Set the device header field of the last device
| |
| driver to -1.
| |
|
| |
| Attribute Field
| |
|
| |
| The attribute field identifies the device to DOS 4.00.
| |
|
| |
| Bit 15
| |
|
| |
| Bit 15 identifies whether the device is a block device or a character device.
| |
| If bit 15 is set to 0, this indicates a block device. Setting bit 15 to 1
| |
| indicates a character device. Note how the setting of bit 15 affects the
| |
| interpretation of the setting of the bits below.
| |
|
| |
| Bit 14
| |
|
| |
| Bit 14, for both character and block devices, tells DOS 4.00 whether the
| |
| device driver can handle control strings through IOCtl 44H, AL=2 through
| |
| AL=5. Set bit 14 to 1 if control strings can be processed. IOCtl
| |
| subfunctions permit the device driver to interpret the information passed to
| |
| it, such as setting a baud rate or changing form lengths, without performing
| |
| standard reads and writes. Set bit 14 to 0 if control strings cannot be
| |
| processed. DOS 4.00 will return an error if an IOCtl is issued to send or
| |
| receive control strings and bit 14 is set to 0.
| |
|
| |
| Bit 13
| |
|
| |
| Bit 13 is used for both block and character devices. For block devices, set
| |
| bit 13 to 0 if the media is an IBM format. Set bit 13 to 1 if the media is a
| |
| non-IBM format. For character devices, set bit 13 to 0 if the driver
| |
| supports output-until-busy. Set bit 13 to 1 if it does not.
| |
|
| |
| With the support of output-until-busy, the device driver will send characters
| |
| to the device if the device is ready. If the device is not ready, the device
| |
| driver will immediately return an error.
| |
|
| |
| Bit 12
| |
|
| |
| Bit 12 is reserved.
| |
|
| |
| Bit 11
| |
|
| |
| Set bit 11 if the device driver can handle removable media. This bit is
| |
| called the open/close removable media bit.
| |
|
| |
| Bits 10 through 7
| |
|
| |
| Bits 10 through 7 are reserved.
| |
|
| |
| Bit 6
| |
|
| |
| Bit 6 is the generic IOCtl bit for both character and block device drivers.
| |
| If this bit is set to 1, the device driver supports generic IOCtl function
| |
| calls. Setting this bit to 1 also indicates support of the Get/Set Logical
| |
| Drive function for a block device driver.
| |
|
| |
| Bits 5 and 4
| |
|
| |
| Bits 5 and 4 are reserved.
| |
|
| |
| Bit 3
| |
|
| |
| Set bit 3 to 1 if the character device is a clock device; set bit 3 to 0 if
| |
| it is not.
| |
|
| |
| Bit 2
| |
|
| |
| Set bit 2 to 1 if the character device is the NUL device; set bit 2 to 0 if
| |
| it is not. Setting the bit tells DOS 4.00 whether the NUL device is being
| |
| used. The NUL device cannot be reassigned.
| |
|
| |
| Bit 1
| |
|
| |
| If bit 15 is set to 0 for a character device, set bit 1 to 1 to indicate that
| |
| the character device is the current standard output device. If bit 15 is set
| |
| to 1 for a block device, set bit 1 to 1 to indicate support for 32-bit sector
| |
| numbers; otherwise 16-bit sector number support is assumed.
| |
|
| |
| Bit 0
| |
|
| |
| Set bit 0 to 1 if the character device is the current standard input device;
| |
| set bit 0 to 0 if it is not the current standard input device.
| |
|
| |
| Pointers to Strategy Routine and Interrupt Routines
| |
|
| |
| When DOS 4.00 passes a request to a device driver, it calls the device driver
| |
| twice. These two fields point to the first and second entry points: the
| |
| strategy routine and the interrupt routine. The fields are word values, so
| |
| they must be in the same segment as the device header.
| |
|
| |
| Name/Unit Field
| |
|
| |
| These 8-byte fields identify a character device by name or a block device by
| |
| unit. A character device name is left-justified followed by spaces, if
| |
| necessary. For block devices, although DOS 4.00 automatically fills in this
| |
| field with the value of number of units returned by INIT call, you may choose
| |
| to place the number of units in the first place.
| |
|
| |
| THE STRATEGY ROUTINE
| |
|
| |
| DOS 4.00 calls a device driver at the strategy routine at first, passing in a
| |
| request packet the information describing what DOS 4.00 wants the device
| |
| driver to do.
| |
|
| |
| The strategy routine does not perform the request but queues the request or
| |
| saves a pointer to the request packet.
| |
|
| |
| THE INTERRUPT ROUTINES
| |
|
| |
| DOS 4.00 calls the device driver's interrupt routine with no parameters
| |
| immediately after the strategy routine returns. An interrupt routine's
| |
| function is to perform the operation based on the queued request, process any
| |
| data in the request packet, and set up information being returned to DOS
| |
| 4.00.
| |
|
| |
| It is the responsibility of the device driver to preserve the system state.
| |
| For example, the device driver must save all registers on entry and restore
| |
| them on exit. The stack maintained by DOS 4.00 is used to save all
| |
| registers. If more stack space is needed, it is the device driver's
| |
| responsibility to allocate and maintain an additional stack.
| |
|
| |
| All calls to device drivers are FAR calls. FAR returns should be executed to
| |
| return to DOS 4.00.
| |
|
| |
| HOW DOS 4.00 PASSES A REQUEST
| |
|
| |
| DOS 4.00 passes a pointer in ES:BX to the request packet. The packet
| |
| consists of a request header that contains information common to all
| |
| requests, followed by data pertinent to the request being made.
| |
|
| |
| The structure of the request header is shown below.
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Length of the request header and subsequent data BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Unit code for block devices only BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Command code BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Status WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Reserved 8-BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Data VARIABLE |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| Length Field
| |
|
| |
| The length field identifies the length of the request header and subsequent
| |
| data in bytes.
| |
|
| |
| Unit Code Field
| |
|
| |
| The unit code field identifies the requesting unit in a block device driver.
| |
| If a block device driver has three units defined, for example, the possible
| |
| values for the unit code field are 0, 1, or 2.
| |
|
| |
| Command Code Field
| |
|
| |
| The command code identifies the request. See "Responding to Requests" on
| |
| page 11-8 for a list of command code values and request descriptions.
| |
|
| |
| Status Field
| |
|
| |
| The status word field is zero on entry and is set by the driver interrupt
| |
| routine on return.
| |
|
| |
| Bit 15
| |
|
| |
| Bit 15 is the error bit. If bit 15 is set to 1, the low order 8 bits of the
| |
| status word (7-0) indicate the error code.
| |
|
| |
| Bits 14 - 10
| |
|
| |
| Bits 14 through 10 are reserved.
| |
|
| |
| Bit 9
| |
|
| |
| Bit 9 is the busy bit. As a response to status request call, character
| |
| device drivers can set the busy bit to indicate whether or not a device is
| |
| ready to perform input and output requests. Block device drivers can set the
| |
| busy bit to indicate removable or nonremovable media. See "Character Input
| |
| and Output Status Requests" on page 11-21 and "Removable Media Request" on
| |
| page 11-23 for more information about the calls.
| |
|
| |
| Bit 8
| |
|
| |
| Bit 8 is the done bit. If set, the operation is complete. The driver sets
| |
| the done bit to 1 when it exits.
| |
|
| |
| Bits 7 - 0
| |
|
| |
| Bits 7 through 0 are the low order 8 bits of the status word. If bit 15 is
| |
| set, bits 7 through 0 contain the error codes. The error codes and errors
| |
| are:
| |
|
| |
| CODES MEANING
| |
| 00 Write protect violation
| |
| 01 Unknown unit
| |
| 02 Device not ready
| |
| 03 Unknown command
| |
| 04 CRC error
| |
| 05 Bad drive request structure length
| |
| 06 Seek error
| |
| 07 Unknown media
| |
| 08 Sector not found
| |
| 09 Printer out of paper
| |
| 0A Write fault
| |
| 0B Read fault
| |
| 0C General failure
| |
| 0D Reserved
| |
| 0E Reserved
| |
| 0F Invalid disk change
| |
|
| |
| RESPONDING TO REQUESTS
| |
|
| |
| Each request packet that is passed to the device driver contains a command
| |
| code value in the request header to tell the driver which function to
| |
| perform. The table below contains the DOS 4.00 device interface command code
| |
| values and the functions to be performed when these values are passed with
| |
| data. Note that some of these functions are specific to either a block
| |
| device or a character device.
| |
|
| |
| Following this table are detailed descriptions of request data structures and
| |
| what the interrupt routines are expected to do. Some of these descriptions
| |
| pertain to more than one command code.
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | COMMAND REQUEST DEVICE |
| |
| | CODE DESCRIPTION TYPE |
| |
| +---------------------------------------------------------------------------+
| |
| | 0 Initialization Both |
| |
| +---------------------------------------------------------------------------+
| |
| | 1 Media check Block |
| |
| +---------------------------------------------------------------------------+
| |
| | 2 Build BPB Block |
| |
| +---------------------------------------------------------------------------+
| |
| | 3 IOCtl input (called only if bit 14 of attribute is Both |
| |
| | set to 1) |
| |
| +---------------------------------------------------------------------------+
| |
| | 4 Input (read) Both |
| |
| +---------------------------------------------------------------------------+
| |
| | 5 Nondestructive input no wait Character |
| |
| +---------------------------------------------------------------------------+
| |
| | 6 Input status Character |
| |
| +---------------------------------------------------------------------------+
| |
| | 7 Input flush Character |
| |
| +---------------------------------------------------------------------------+
| |
| | 8 Output (write) Both |
| |
| +---------------------------------------------------------------------------+
| |
| | 9 Output (write with verify) Block |
| |
| +---------------------------------------------------------------------------+
| |
| | 10 Output status Character |
| |
| +---------------------------------------------------------------------------+
| |
| | 11 Output flush Character |
| |
| +---------------------------------------------------------------------------+
| |
| | 12 IOCtl output (called only if bit 14 of attribute is Both |
| |
| | set to 1 |
| |
| +---------------------------------------------------------------------------+
| |
| | 13 Device open (called only if bit 11 of attribute is Both |
| |
| | set to 1) |
| |
| +---------------------------------------------------------------------------+
| |
| | 14 Device close (called only if bit 11 of attribute is Both |
| |
| | set to 1) |
| |
| +---------------------------------------------------------------------------+
| |
| | 15 Removable media (called only if bit 11 of attribute Block |
| |
| | is set to 1) |
| |
| +---------------------------------------------------------------------------+
| |
| | 19 Generic IOCtl Request (called Both |
| |
| | only if bit 6 of attribute is set to 1) |
| |
| +---------------------------------------------------------------------------+
| |
| | 23 Get logical device (called only if bit 6 of Block |
| |
| | attribute is set to 1) |
| |
| +---------------------------------------------------------------------------+
| |
| | 24 Set logical device (called only if bit 6 of Block |
| |
| | attribute is set to 1) |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| INITIALIZATION REQUEST
| |
|
| |
| COMMAND CODE = 0
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Request header 13-BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Number of units (not set by character devices) BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Ending address of resident program code DWORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Pointer to BPB array (not set by character devices) pointer DWORD |
| |
| | to remainder of arguments |
| |
| +---------------------------------------------------------------------------+
| |
| | Drive number BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | CONFIG.SYS Error Message control flag WORD |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| The driver must do the following:
| |
|
| |
| Set the number of units (block devices only).
| |
| Set up the pointer to the BPB array (block devices only).
| |
| Perform any initialization code (to modems, printers, and others).
| |
| Set the ending address of the resident program code.
| |
| Set the status word in the request header.
| |
|
| |
| To obtain information passed from CONFIG.SYS to a device driver at
| |
| initialization time, the BPB pointer field points to a buffer containing the
| |
| information passed in CONFIG.SYS following the =. This string may end with
| |
| either a carriage return (0DH) or a linefeed (0AH). This information is
| |
| read-only. Only system calls 01H-0CH and 30H can be issued by the
| |
| initialization code of the driver.
| |
|
| |
| The last byte parameter contains the drive letter for the first unit of a
| |
| block driver. For example, 0=A, 1=B and so forth.
| |
|
| |
| If an initialization routine determines that it cannot set up the device and
| |
| wants to terminate without using any memory, use the following procedure:
| |
|
| |
| Set the number of units to 0.
| |
| Set the ending address offset to 0.
| |
| Set the ending address segment to the code segment (CS).
| |
|
| |
| If there are multiple device drivers in a single memory image file, the
| |
| ending address returned by the last initialization called is the one DOS 4.00
| |
| uses. IBM recommends that all device drivers in a single memory image file
| |
| return the same ending address.
| |
|
| |
| If initialization of your device driver fails, and you want the system to
| |
| display the ERROR IN CONFIG.SYS LINE # error message, set the CONFIG.SYS
| |
| error message control flag to a non-zero value.
| |
|
| |
| MEDIA CHECK REQUEST
| |
|
| |
| COMMAND CODE = 1
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Request header 13-BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Media descriptor from DOS 4.00 BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Return BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | A pointer to the previous volume ID (if bit 11 = 1 and disk DWORD |
| |
| | change is returned) |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| When the command code field is 1, DOS 4.00 calls Media Check for a drive unit
| |
| and passes its current Media Descriptor byte. See "Media Descriptor Byte."
| |
| Media Check returns one of the following:
| |
|
| |
| Media not changed
| |
| Media changed
| |
| Not sure
| |
| Error code.
| |
|
| |
| The driver must perform the following:
| |
|
| |
| Set the status word in the request header.
| |
| Set the return byte to:
| |
|
| |
| -1 for "media changed"
| |
| 0 for "not sure"
| |
| 1 for "media not changed."
| |
|
| |
| The driver uses the following method to determine how to set the return byte:
| |
|
| |
| If the media is nonremovable (a fixed disk), set the return byte to 1.
| |
| If less than 2 seconds since last successful access, set the return byte
| |
| to 1.
| |
| If changeline not available, set the return byte to 0.
| |
| If changeline is available but not active, set the return byte to 1.
| |
| If the media byte in the new BPB does not match the old media byte, set
| |
| the return byte to -1.
| |
| If the current volume ID matches the previous volume ID, or if the serial
| |
| number matches the previous serial number, set the return byte to 0.
| |
|
| |
| Media Descriptor Byte
| |
|
| |
| Currently the media descriptor byte has been defined for some media types.
| |
| This byte should be identical to the media byte if the device has the non-IBM
| |
| format bit off. These predefined values are:
| |
|
| |
| Media descriptor
| |
| byte --> 1 1 1 1 1 x x x
| |
| bits --> 7 6 5 4 3 2 1 0
| |
|
| |
| BIT MEANING
| |
| 0 1=2-sided 0=not 2-sided
| |
| 1 1=8 sector 0=not 8 sector
| |
| 2 1=removable 0=not removable
| |
| 3-7 must be set to 1
| |
|
| |
| NOTE: An exception to the above is that the media descriptor byte value of
| |
| F0, which is used to indicate any media types not defined, and F9,
| |
| which is used for 5.25-inch media with 2 sides and 15 sectors/tracks.
| |
|
| |
| Examples of current DOS 4.00 media descriptor bytes:
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | DISK # SECTORS/ MEDIA |
| |
| | TYPE SIDES TRACK DESCRIPTOR |
| |
| +---------------------------------------------------------------------------+
| |
| | Fixed disk -- -- F8H |
| |
| +---------------------------------------------------------------------------+
| |
| | 5.25 inch 2 15 F9H |
| |
| +---------------------------------------------------------------------------+
| |
| | 5.25 inch 1 9 FCH |
| |
| +---------------------------------------------------------------------------+
| |
| | 5.25 inch 2 9 FDH |
| |
| +---------------------------------------------------------------------------+
| |
| | 5.25 inch 1 8 FEH |
| |
| +---------------------------------------------------------------------------+
| |
| | 5.25 inch 2 8 FFH |
| |
| +---------------------------------------------------------------------------+
| |
| | 8 inch 1 26 FEH |
| |
| +---------------------------------------------------------------------------+
| |
| | 8 inch 2 26 FDH |
| |
| +---------------------------------------------------------------------------+
| |
| | 8 inch 2 8 FEH |
| |
| +---------------------------------------------------------------------------+
| |
| | 3.5 inch 2 9 F9H |
| |
| +---------------------------------------------------------------------------+
| |
| | 3.5 inch 2 18 F0H |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| To determine whether you are using a single-sided or a double-sided diskette,
| |
| attempt to read the second side. If an error occurs, you may assume the
| |
| diskette is single-sided. Media descriptor F0H may be used for those media
| |
| types not described earlier. Programs should not use the media descriptor
| |
| values to distinguish media. DOS 4.00 internal routines use information in
| |
| the BIOS parameter block (BPB) to determine the media type of IBM-formatted
| |
| diskettes. These media descriptor bytes do not necessarily indicate a unique
| |
| media type.
| |
|
| |
| For 8-inch diskettes:
| |
|
| |
| FEH (IBM 3740 Format) -- Single-sided, single-density, 128 bytes per
| |
| sector, soft-sectored, 4 sectors per allocation unit, 1 reserved sector,
| |
| 2 FATs, 68 directory entries, 77*26 sectors.
| |
|
| |
| FDH (IBM 3740 Format) -- Double-sided, single-density, 128 bytes per
| |
| sector, soft-sectored, 4 sectors per allocation unit, 4 reserved sectors,
| |
| 2 FATs, 68 directory entries, 77*26*2 sectors.
| |
|
| |
| FEH -- Double-sided, double-density, 1024 bytes per sector, soft
| |
| sectored, 1 sector per allocation unit, 1 reserved sector, 2 FATs, 192
| |
| directory entries, 77*8*2 sectors.
| |
|
| |
| BUILD BPB REQUEST
| |
|
| |
| COMMAND CODE = 2
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Request header 13-BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Media descriptor from DOS 4.00 BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Transfer address (buffer address) DWORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Pointer to BPB table DWORD |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| DOS 4.00 calls Build BPB (BIOS Parameter Block) under the following two
| |
| conditions:
| |
|
| |
| If "Media Changed" is returned
| |
| If "Not Sure" is returned, there are no used buffers. Used buffers are
| |
| buffers with changed data not yet written to the disk.
| |
|
| |
| The driver must do the following:
| |
|
| |
| Set the pointer to the BPB
| |
| Set the status word in the request header.
| |
|
| |
| The device driver must determine the media type that is in the unit to return
| |
| the pointer to the BPB table. In previous versions of IBMBIO, the FAT ID
| |
| byte determined the structure and layout of the media. The FAT ID byte has
| |
| only eight possible values (F8 through FF), so, as new media types are
| |
| invented, the available values will soon be exhausted. With the varying
| |
| media layouts, DOS 4.00 needs to be aware of the location of the FATs and
| |
| directories before it asks to read them.
| |
|
| |
| The following paragraphs explain the method DOS 4.00 uses to determine the
| |
| media type.
| |
|
| |
| The information relating to the BPB for a particular media is kept in the
| |
| boot sector for the media. The format of the boot sector is as follows:
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | A 2-byte short JMP instruction (EBH), followed by a NOP WORD |
| |
| | instruction (90H). |
| |
| +---------------------------------------------------------------------------+
| |
| | Product name and version 8 BYTES |
| |
| +---------------------------------------------------------------------------+
| |
| | Bytes per sector; must be power of 2 WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Sectors per allocation unit; must be power of 2 BYTE |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Reserved sectors starting at logical sector 0 WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Number of FATs BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Maximum number of root directory entries WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Total number of sectors in media including the boot sector, WORD |
| |
| | FAT areas, and directories |
| |
| +---------------------------------------------------------------------------+
| |
| | Media descriptor BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Number of sectors occupied by a FAT WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Sectors per track WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Number of heads WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Number of hidden sectors WORD |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| The BPB information contained in the boot sector starts with the Bytes per
| |
| Sector entry. The last three words are intended to help the device driver
| |
| identify the media. The number of heads is useful for supporting different
| |
| multihead drives with the same storage capacity but a different number of
| |
| surfaces. The number of hidden sectors is useful for supporting drive
| |
| partitioning schemes.
| |
|
| |
| For drivers that support volume identification and disk change, this call
| |
| causes a new volume identification to be read from the disk. This call
| |
| indicates that the disk has changed in a permissible manner.
| |
|
| |
| To handle the partition that is bigger than 32MB, or one that starts beyond
| |
| or crosses the 32MB boundary, DOS 4.00 defines an extended BPB structure.
| |
| Depending on the size of the media, you can use either the existing BPB or
| |
| the extended one, which contains an additional DWORD field to indicate the
| |
| size of the partition in sectors.
| |
|
| |
| Bit 1 of the attribute field in the block device driver header indicates
| |
| whether the device can process 32-bit sector numbers. Set bit 1 to indicate
| |
| 32-bit support.
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Bytes per sector WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Sectors per allocation unit BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Reserved sectors starting at logical sector 0 WORD |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Number of FATs -- 0 if not a FAT system BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Maximum number of root directory entries WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Total number of sectors in the media. This field is used to WORD |
| |
| | define a partition that is less than 32MB. Setting this |
| |
| | field to 0 indicates to use the total (32-bit) number of |
| |
| | sectors in the media below. |
| |
| +---------------------------------------------------------------------------+
| |
| | Media descriptor BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Number of sectors occupied by a FAT WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Sectors per track WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Number of heads WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Number of hidden sectors DWORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Total (32-bit) number of sectors in the media. This field is DWORD |
| |
| | used to define a partition that is greater than 32MB, or one |
| |
| | that crosses the 32MB boundary. |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| The extended BPB is a superset of the traditional BPB structure. To achieve
| |
| the maximum compatibility between this structure and that of the traditional
| |
| BPB, DOS 4.00 uses the following rule:
| |
|
| |
| If (the number of hidden sectors plus the total number of sectors in the
| |
| media) is greater than 64KB, use the 32-bit total number of sectors in
| |
| the media entry (DWORD).
| |
|
| |
| Otherwise, use the TOTAL NUMBER OF SECTORS IN THE MEDIA entry (WORD).
| |
|
| |
| A boot record exists at the beginning of each disk partition and each
| |
| extended DOS 4.00 partition volume. DOS 4.00 automatically creates the
| |
| extended boot record. The format of the extended boot record is:
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | A 2-byte short JMP instruction (EBH) followed by a NOP WORD |
| |
| | instruction (90H). |
| |
| +---------------------------------------------------------------------------+
| |
| | Product name and version 8 BYTES |
| |
| +---------------------------------------------------------------------------+
| |
| | Extended BPB 25 BYTES |
| |
| +---------------------------------------------------------------------------+
| |
| | Physical drive number BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Reserved BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Extended boot record signature BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Volume serial number DWORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Volume label 11 BYTES |
| |
| +---------------------------------------------------------------------------+
| |
| | Reserved 8 BYTES |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| NOTE: The value of Extended boot record signature is 29H. The value of the
| |
| physical drive number is always 0H or 80H.
| |
|
| |
| On all requests to extended drivers with a sector number in their request
| |
| headers, the sector number is a DWORD. The standard DOS 4.00 block device
| |
| drivers set the attribute bit 1 for 32-bit support.
| |
|
| |
| For each call to a device driver, DOS 4.00 checks to see if the starting
| |
| sector number passed in the request can be supported by the device driver.
| |
| If this value is greater than 64K for an old-style device driver, DOS 4.00
| |
| returns an UNKNOWN MEDIA (07H) device driver error.
| |
|
| |
| INPUT AND OUTPUT REQUESTS
| |
|
| |
| COMMAND CODES = 3, 4, 8, 9, 12
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Request header 13-BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Media descriptor byte BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Transfer address (buffer address) DWORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Byte/sector count WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Starting sector number (If -1, use DWORD starting sector WORD |
| |
| | number. This entry has no meaning for a character device.) |
| |
| +---------------------------------------------------------------------------+
| |
| | For DOS 3.0 to DOS 4.00, pointer to the volume identification DWORD |
| |
| | if error code 0FH is returned |
| |
| +---------------------------------------------------------------------------+
| |
| | Starting 32-bit sector number. (Use this entry to the block DWORD |
| |
| | device driver with the attribute bit 1 set.) |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| The DOS 4.00 INPUT/OUTPUT request structure can process 32-bit sector
| |
| numbers, providing support for media of more than 4 billion sectors.
| |
|
| |
| The driver must do the following:
| |
|
| |
| Set the status word in the request header
| |
| Perform the requested function
| |
| Set the actual number of sectors or bytes transferred.
| |
|
| |
| No error checking is performed on an IOCtl call. However, the driver must
| |
| set the return sector or byte count to the actual number of bytes
| |
| transferred.
| |
|
| |
| Under certain circumstances the block device driver may be asked to do a
| |
| WRITE operation of 64KB that seems to be a wraparound of the transfer address
| |
| in the device driver request packet. This occurs because an optimization is
| |
| added to the WRITE code in DOS 4.00. It will only happen on WRITEs that are
| |
| within a sector size of 64KB on files that are being extended past the
| |
| current end of file. The block device driver is allowed to ignore the
| |
| balance of the WRITE that wraps around. For example, a WRITE of 10000H bytes
| |
| of sectors with a transfer address of XXXX:1 ignores the last two bytes.
| |
|
| |
| Remember that a program using DOS 4.00 function calls cannot request an input
| |
| or output operation of more than FFFFH bytes because a wrap around in the
| |
| transfer buffer segment must occur. You can ignore bytes that would have
| |
| wrapped around in the transfer segment.
| |
|
| |
| If the driver returns an error code of 0FH (Invalid Disk Change), it must
| |
| provide a DWORD pointer to an ASCIIZ string identifying the correct volume ID
| |
| and the system prompts the user to reinsert the disk.
| |
|
| |
| The reference count of open files on the disk maintained by OPEN and CLOSE
| |
| calls allows the driver to determine when to return error 0FH. If there are
| |
| no open files (reference count=0) and the disk has been changed, the I/O is
| |
| valid, and error 0FH is not returned. If there are open files (reference
| |
| count > 0) and the disk has been changed, an error 0FH situation may exist.
| |
| DOS 4.00 IBMDOS.COM will request an OPEN or CLOSE function only if SHARE is
| |
| loaded.
| |
|
| |
| NONDESTRUCTIVE INPUT NO WAIT REQUEST
| |
|
| |
| COMMAND CODE = 5
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Request header 13-BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Byte read from device BYTE |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| The driver must do the following:
| |
|
| |
| Return a byte from the device.
| |
| Set the status word in the request header.
| |
|
| |
| If the character device returns busy bit = 0, meaning there are characters in
| |
| buffer, the next character that would be read is returned. This character is
| |
| not removed from the input buffer, (that is, nondestructive input). This
| |
| call allows DOS 4.00 to look ahead one input character.
| |
|
| |
| CHARACTER INPUT AND OUTPUT STATUS REQUESTS
| |
|
| |
| COMMAND CODES = 6, 10
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Request header 13-BYTE |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| The driver must do the following:
| |
|
| |
| Perform the requested function.
| |
| Set the busy bit.
| |
| Set the status word in the request header.
| |
|
| |
| The busy bit is set differently for output and input.
| |
|
| |
| Output on Character Devices
| |
|
| |
| If the busy bit is 1 on return, a write request would wait for completion of
| |
| a current request. If the busy bit is 0, no request is waiting or running.
| |
| Therefore, a write request would start immediately.
| |
|
| |
| Input on Character Devices with a Buffer
| |
|
| |
| If the busy bit is 1 on return, a read request goes to the physical device.
| |
| If the busy bit is 0, characters are in the device buffer and a read returns
| |
| quickly. This also indicates that the user has typed something. DOS 4.00
| |
| assumes that all character devices have a type-ahead input buffer. Devices
| |
| that do not have this buffer should always return busy = 0 so that DOS 4.00
| |
| does not loop endlessly, waiting for information to be put in a buffer that
| |
| does not exist.
| |
|
| |
| CHARACTER INPUT AND OUTPUT FLUSH REQUESTS
| |
|
| |
| COMMAND CODES = 7, 11
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Request header 13-BYTE |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| This call tells the driver to flush (terminate) all pending requests of which
| |
| it has knowledge. Its primary use is to flush the input queue on character
| |
| devices.
| |
|
| |
| The driver must set the status word in the Request Header upon return.
| |
|
| |
| OPEN AND CLOSE REQUESTS
| |
|
| |
| COMMAND CODES = 13, 14
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Request header 13-BYTE |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| These calls are designed to give the device information about current file
| |
| activity on the device if bit 11 of the attribute word is set.
| |
|
| |
| On block devices, these calls can be used to manage local buffering. The
| |
| device can keep a reference count. Every OPEN increases the reference count.
| |
| Every CLOSE decreases the device reference count. When the reference count
| |
| is 0, there are no open files on the device. Therefore, the device should
| |
| flush buffers inside the device to which it has written because the user can
| |
| change the media on a removable media drive. If the media has been changed,
| |
| reset the reference count to 0 without flushing the buffers.
| |
|
| |
| These calls are more useful on character devices. The OPEN call can send a
| |
| device an initialization string. On a printer, the call can send a string to
| |
| set the font or the page size so the printer is always in a known state at
| |
| the start of an I/O stream.
| |
|
| |
| Similarly, the CLOSE call can send a post string, such as a form feed, at the
| |
| end of an I/O stream.
| |
|
| |
| Using IOCtl to set the preliminary and ending strings provides a flexible
| |
| mechanism for serial I/O device stream control.
| |
|
| |
| REMOVABLE MEDIA REQUEST
| |
|
| |
| COMMAND CODE = 15
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Request header 13-BYTE |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| To use this call, set bit 11 of the attribute field to 1. Block devices can
| |
| use this call only by way of a subfunction of the IOCtl function call (44H).
| |
|
| |
| This call is useful because it notifies a utility if it is dealing with a
| |
| removable or nonremovable media drive. For example, the FORMAT utility needs
| |
| to know whether a drive is removable or nonremovable because it displays
| |
| different versions of some prompts.
| |
|
| |
| The information is returned in the busy bit of the status word. If the busy
| |
| bit is 1, the media is nonremovable. If the busy bit is 0, the media is
| |
| removable.
| |
|
| |
| No error bit checking is performed. It is assumed that this call always
| |
| succeeds.
| |
|
| |
| GENERIC IOCTL REQUEST
| |
|
| |
| COMMAND CODE = 19
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Request header 13-BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Major function BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Minor function BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Contents of SI WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Contents of DI WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Pointer to Generic IOCTL request packet DWORD |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| The driver must:
| |
|
| |
| Support the functions described under Generic IOCtl request
| |
| Maintain its own track table (TrackLayout).
| |
|
| |
| See Appendix C, "I/O Control for Devices (IOCtl)" on page C-1 for a
| |
| description of the functions provided by generic IOCtl requests.
| |
|
| |
|
| |
| GET LOGICAL DEVICE REQUEST
| |
|
| |
| COMMAND CODE = 23
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Request header 13-BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Input (unit code) BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Command code BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Status WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Reserved DWORD |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| SET LOGICAL DEVICE REQUEST
| |
|
| |
| COMMAND CODE = 24
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FIELD LENGTH |
| |
| +---------------------------------------------------------------------------+
| |
| | Request header 13-BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Input (unit code) BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Command code BYTE |
| |
| +---------------------------------------------------------------------------+
| |
| | Status WORD |
| |
| +---------------------------------------------------------------------------+
| |
| | Reserved DWORD |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| CLOCK$ DEVICE DRIVER EXAMPLE
| |
|
| |
| This feature is a "Real-Time Clock" Board. To allow this board to be
| |
| integrated into the system for TIME and DATE, a special device driver is
| |
| specified by an attribute word, the CLOCK$ device. This device driver
| |
| defines and performs functions like any other character device driver. Most
| |
| functions will be set done bit, reset error bit, return. When a read or
| |
| write to this device occurs, 6 bytes are transferred. The first 2 bytes are
| |
| a word, which is the count of days since 1-1-80. The third byte is minutes;
| |
| the fourth is hours; the fifth is hundredths of seconds; and the sixth is
| |
| seconds. Reading the CLOCK$ device gets the date and time; writing to it
| |
| sets the date and time.
| |
|
| |
| PART 3. APPENDIXES
| |
|
| |
| </PRE>
| |
| | |
| ==Appendix A==
| |
| | |
| </PRE>
| |
| APPENDIX A. DOS 4.00 INTERRUPTS 13
| |
| 20H Program Terminate 21
| |
| 21H Function Request 41
| |
| 22H Terminate Address 46
| |
| 23H Ctrl-Break Exit Address 53
| |
| 24H Critical Error Handler Vector 83
| |
| 25H/26H Absolute Disk Read/Write 287
| |
| 27H Terminate but Stay Resident 353
| |
| 28H-2EH Reserved for DOS 4.00 392
| |
| 2FH Multiplex Interrupt 396
| |
| 30H-3FH Reserved for DOS 4.00 695
| |
|
| |
| APPENDIX A. DOS 4.00 INTERRUPTS
| |
|
| |
| This chapter contains information to support use of the DOS 4.00 interrupts.
| |
|
| |
| DOS 4.00 reserves interrupt types 20H to 3FH for its use. Absolute memory
| |
| locations 80H to FFH are reserved by DOS 4.00. All interrupt values are in
| |
| hexadecimal.
| |
|
| |
| 20H PROGRAM TERMINATE
| |
|
| |
| Issue interrupt 20H to exit from a program. This vector transfers to the
| |
| logic in DOS 4.00 to restore the terminate address, the Ctrl-Break address,
| |
| and the critical error exit address to the values they had on entry to the
| |
| program. All file buffers are flushed and all handles are closed. You
| |
| should close all files changed in length (see function call 10H and 3EH)
| |
| before issuing this interrupt. If the changed file is not closed, its
| |
| length, date, and time are not recorded correctly in the directory.
| |
|
| |
| For a program to pass a completion code or an error code when terminating, it
| |
| must use either function call 4CH (Terminate a Process) or 31H (Terminate
| |
| Process and Stay Resident). These two methods are preferred over using
| |
| interrupt 20H, and the codes returned by them can be interrogated in batch
| |
| processing. See function call 4CH for information on the ERRORLEVEL
| |
| subcommand of batch processing.
| |
|
| |
| IMPORTANT: Before you issue interrupt 20H, your program must ensure that the
| |
| CS register contains the segment address of its program segment prefix.
| |
|
| |
| 21H FUNCTION REQUEST
| |
|
| |
| Refer to each function call issued within 21H in Appendix B, "DOS 4.00
| |
| Function Calls" on page B-1.
| |
|
| |
| 22H TERMINATE ADDRESS
| |
|
| |
| Control transfers to the address at this interrupt location when the program
| |
| terminates. This address is copied into the program's Program Segment Prefix
| |
| at the time the segment is created. You should not issue this interrupt; the
| |
| EXEC function call does this for you.
| |
|
| |
| 23H CTRL-BREAK EXIT ADDRESS
| |
|
| |
| If the user presses the Ctrl and Break keys during standard input, standard
| |
| output, standard printer, or asynchronous communications adapter operations,
| |
| an interrupt 23H is executed. If BREAK is on, the interrupt 23H is checked
| |
| on most function calls (except calls 06H and 07H). If the user-written
| |
| Ctrl-Break routine saves all registers, it may end with a
| |
| return-from-interrupt instruction (IRET) to continue program execution.
| |
|
| |
| If the user-written interrupt program returns with a long return, the carry
| |
| flag is used to determine whether the program will be ended. If the carry
| |
| flag is set, the program is ended, otherwise execution continues (as with a
| |
| return by IRET).
| |
|
| |
| If the user-written Ctrl-Break interrupt uses function calls 09H or 0AH, then
| |
| &hat.C, carriage-return and linefeed are output. If execution is continued
| |
| with an IRET, I/O continues from the start of the line.
| |
|
| |
| When the interrupt occurs, all registers are set to the value they had when
| |
| the original function call to DOS 4.00 was made. There are no restrictions
| |
| on what the Ctrl-Break handler is allowed to do, including DOS 4.00 function
| |
| calls, as long as the registers are unchanged if IRET is used.
| |
|
| |
| When the program creates a new segment and loads in a second program it
| |
| changes the Ctrl-Break address. The termination of the second program and
| |
| return to the first causes the Ctrl-Break address to be restored to the value
| |
| it had before execution of the second program. It is restored from the
| |
| second program's Program Segment Prefix. You should not issue this
| |
| interrupt.
| |
|
| |
| 24H CRITICAL ERROR HANDLER VECTOR
| |
|
| |
| A critical error is returned when a DOS function cannot be performed. This
| |
| error is frequently caused by a hardware condition, such as the printer being
| |
| out of paper, a diskette drive door open, or a diskette out of space. When a
| |
| critical error occurs within DOS 4.00, control is transferred with an
| |
| interrupt 24H. On entry to the error handler, AH will have its bit 7=0
| |
| (high-order bit) if the error was a disk error (the most common occurrence),
| |
| bit 7=1 if it was not.
| |
|
| |
| BP:SI contains the address of a Device Header Control Block from which
| |
| additional information can be retrieved. See page A-5.
| |
|
| |
| The registers are set up for a retry operation, and an error code is in the
| |
| lower half of the DI register with the upper half undefined. The error codes
| |
| follow:
| |
|
| |
| ERROR CODE MEANING
| |
| 0 Attempt to write on write-protected diskette
| |
| 1 Unknown unit
| |
| 2 Drive not ready
| |
| 3 Unknown command
| |
| 4 Data error (CRC)
| |
| 5 Bad request structure length
| |
| 6 Seek error
| |
| 7 Unknown media type
| |
| 8 Sector not found
| |
| 9 Printer out of paper
| |
| A Write fault
| |
| B Read fault
| |
| C General failure
| |
|
| |
| The user stack is in effect and contains the following from top to bottom:
| |
|
| |
| IP DOS 4.00 registers from issuing INT 24H
| |
|
| |
| CS
| |
| FLAGS
| |
| AX User registers at time of original
| |
| BX INT 21H request
| |
| CX
| |
| DX
| |
| SI
| |
| DI
| |
| BP
| |
| DS
| |
| ES
| |
| IP From the original interrupt 21H
| |
| CS from the user to DOS 4.00
| |
| FLAGS
| |
|
| |
| The registers are set such that if an IRET is executed, DOS 4.00 responds
| |
| according to (AL) as follows:
| |
|
| |
| (AL) =0 ignore the error.
| |
| =1 retry the operation.
| |
| =2 terminate the program
| |
| through interrupt 22H.
| |
| =3 fail the system call
| |
| in progress.
| |
|
| |
| NOTE: Be careful when choosing ignore as a response because this causes DOS
| |
| 4.00 to believe that an operation has completed successfully when it
| |
| may not have.
| |
|
| |
| To return control from the critical error handler to a user error routine,
| |
| the following should occur:
| |
|
| |
| Before an INT 24H occurs:
| |
|
| |
| 1. The user application initialization code should save the INT 24H vector
| |
| and replace the vector with one pointing to the user error routine.
| |
|
| |
| When the INT 24H occurs:
| |
|
| |
| 2. When the user error routine receives control, it should push the flag
| |
| register onto the stack, and then execute a CALL FAR to the original INT
| |
| 24H vector saved in step 1.
| |
|
| |
| 3. DOS 4.00 gives the appropriate prompt, and waits for the user input
| |
| (Abort, Retry, Fail or Ignore). After the user input, DOS 4.00 returns
| |
| control to the user error routine at the instruction following the CALL
| |
| FAR.
| |
|
| |
| 4. The user error routine can now do any tasks necessary. To return to the
| |
| original application at the point the error occurred, the error routine
| |
| needs to execute an IRET instruction. Otherwise, the user error routine
| |
| should remove the IP, CS, and Flag registers from the stack. Control can
| |
| then be passed to the desired point.
| |
|
| |
| Disk Errors
| |
|
| |
| If it is a hard error on disk (AH bit 7=0), register AL contains the failing
| |
| drive number (0 = drive A, and so on). AH bits 0-2 indicate the affected
| |
| disk area and whether it was a read or write operation, as follows:
| |
|
| |
| Bit 0=0 if read operation,
| |
| 1 if write operation
| |
| Bits 2-1 (affected disk area)
| |
| 0 0 DOS 4.00 area
| |
| 0 1 file allocation table
| |
| 1 0 directory
| |
| 1 1 data area
| |
|
| |
| AH bits 3-5 indicate which responses are valid. They are:
| |
|
| |
| Bit 3=0 if FAIL is not allowed
| |
| =1 if FAIL is allowed
| |
| Bit 4=0 if RETRY is not allowed
| |
| =1 if RETRY is allowed
| |
| Bit 5=0 if IGNORE is not allowed
| |
| =1 if IGNORE is allowed
| |
|
| |
| Handling of Invalid Responses
| |
|
| |
| If IGNORE is specified (AL=0) and IGNORE is not allowed (bit 5=0), make the
| |
| response FAIL (AL=3).
| |
|
| |
| If RETRY is specified (AL=1) and RETRY is not allowed (bit 4=0), make the
| |
| response FAIL (AL=3).
| |
|
| |
| If FAIL is specified (AL=3) and FAIL is not allowed (bit 3=0), make the
| |
| response END (AL=2).
| |
|
| |
| Other Errors
| |
|
| |
| If AH bit 7=1, the error occurred on a character device, or was the result of
| |
| a bad memory image of the FAT. The device header passed in BP:SI can be
| |
| examined to determine which case exists. If the attribute byte high-order
| |
| bit indicates a block device, then the error was a bad FAT. Otherwise, the
| |
| error is on a character device.
| |
|
| |
| If a character device is involved, the contents of AL are unpredictable and
| |
| the error code is in DI as above.
| |
|
| |
| NOTES:
| |
|
| |
| 1. Retry five times before giving this routine control for disk errors.
| |
| When the errors are in the FAT or a directory, retry three times.
| |
|
| |
| 2. For disk errors, this exit is taken only for errors occurring during an
| |
| interrupt 21H function call. It is not used for errors during an
| |
| interrupt 25H or 26H.
| |
|
| |
| 3. This routine is entered in a disabled state.
| |
|
| |
| 4. All registers must be preserved.
| |
|
| |
| 5. This interrupt handler should refrain from using DOS 4.00 function calls.
| |
| If necessary, it may use calls 01H through 0CH, 30H, and 59H. Use of any
| |
| other call destroys the DOS 4.00 stack and leaves DOS 4.00 in an
| |
| unpredictable state.
| |
|
| |
| 6. The interrupt handler must not change the contents of the device header.
| |
|
| |
| 7. If the interrupt handler handles errors itself rather than returning to
| |
| DOS 4.00, it should restore the application program's registers from the
| |
| stack, remove all but the last three words on the stack, then issue an
| |
| IRET. This will return to the program immediately after the INT 21H that
| |
| experienced the error. Note that if this is done, DOS 4.00 will be in an
| |
| unstable state until a function call higher than 0CH is issued;
| |
| therefore, it is not recommended.
| |
|
| |
| The recommended way to end a critical error is to use FAIL and then test
| |
| the extended error code of the INT 21H.
| |
|
| |
| 8. IGNORE requests (AL=0) are converted to FAIL for critical errors that
| |
| occur on FAT or DIR sectors.
| |
|
| |
| 9. Refer to "Responding to Errors" on page B-5 and "Extended Error Codes" on
| |
| page B-5 for information on how to obtain additional error information.
| |
|
| |
| 10. For DOS 4.00, IGNORE requests (AL=0) are converted to FAIL requests for
| |
| certain critical errors (50-79).
| |
|
| |
| The device header pointed to by BP:SI is formatted as follows:
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | DWORD Pointer to next device (FFFFH if last device) |
| |
| +---------------------------------------------------------------------------+
| |
| | WORD Attributes: |
| |
| | Bit 15 = 1 if character device |
| |
| | = 0 if block device |
| |
| | If bit 15 is 1: |
| |
| | Bit 0 = 1 if current standard input |
| |
| | Bit 1 = 1 if current standard output |
| |
| | Bit 2 = 1 if current NULL device |
| |
| | Bit 3 = 1 if current CLOCK device |
| |
| | Bit 14 is the IOCtl bit |
| |
| +---------------------------------------------------------------------------+
| |
| | WORD pointer to device driver strategy entry point. |
| |
| +---------------------------------------------------------------------------+
| |
| | WORD pointer to device driver interrupt entry point. |
| |
| +---------------------------------------------------------------------------+
| |
| | 8-BYTE character device named field for block devices. The first byte is |
| |
| | the number of units. |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| To tell if the error occurred on a block or character device, look at bit 15
| |
| in the attribute field (WORD at BP:SI+4).
| |
|
| |
| If the name of the character device is desired, look at the eight bytes
| |
| starting at BP:SI+10.
| |
|
| |
| 25H/26H ABSOLUTE DISK READ/WRITE
| |
|
| |
| Interrupt vectors 25H and 26H transfer control to the device driver. They
| |
| have been extended to allow direct access to media greater than 32MB in size.
| |
| Their use of the CX register is what distinguishes them from the conventional
| |
| 25H and 26H interrupts. Note that if the conventional format parameters are
| |
| used in an attempt to access media greater than 32MB, an error code of 0207H
| |
| is returned in AX.
| |
|
| |
| The request for extended 25H or 26H is:
| |
|
| |
| MOV AL,DRIVE ; Drive number to process
| |
| ; 0 = A
| |
| ; 1 = B
| |
| ; 2 = C . . .
| |
| LDS BX,PACKET ; Parameter list
| |
| MOV CX,-1 ; Indicates extended format
| |
| INT 25H or 26H ; Issue request to DOS 4.00
| |
| POP AX ; Discard stack word
| |
| JC ERROR ; Error code returned in AX
| |
|
| |
| PACKET LABEL BYTE ; Control packet
| |
| DD RBA ; RBA of first sector
| |
| ; (0 origin)
| |
| DW COUNT ; Number of sectors to I/O
| |
| DD BUFFER ; Data buffer
| |
|
| |
| On return, the original flags are still on the stack (put there by the INT
| |
| instruction). This is necessary because return information is passed back in
| |
| the current flags. Be sure to pop the stack to prevent uncontrolled growth.
| |
|
| |
| WARNING: IF DISK I/O HANDLED BY THIS INTERRUPT EXCEEDS THE LIMIT IMPOSED BY
| |
| THE 64KB DIRECT MEMORY ACCESS BOUNDARY, UNPREDICTABLE RESULTS CAN OCCUR. WE
| |
| RECOMMEND YOU CAREFULLY CHECK THE SECTOR SIZE AND THE NUMBER OF SECTORS TO BE
| |
| READ OR WRITTEN TO BEFORE ISSUING THIS CALL.
| |
|
| |
| The number of sectors specified is transferred between the given drive and
| |
| the transfer address. Logical sector numbers (LSN) are obtained by numbering
| |
| each sector sequentially starting from track 0, head 0, sector 1 (logical
| |
| sector 0) and continuing along the same head, then to the next head until the
| |
| last sector on the last head of the track is counted. Thus, logical sector 1
| |
| is track 0, head 0, sector 2; logical sector 2 is track 0, head 0, sector 3;
| |
| and so on. Numbering continues with sector 1 on head 0 of the next track.
| |
| Note that although the sectors are sequentially numbered (for example,
| |
| sectors 2 and 3 on track 0 in the example above), they may not be physically
| |
| adjacent on the disk, because of interleaving. Note that the mapping is
| |
| different from that used by DOS version 1.10 for dual-sided diskettes.
| |
|
| |
| All registers except the segment registers are destroyed by this call. If
| |
| the transfer was successful, the carry flag (CF) is 0. If the transfer was
| |
| not successful CF=1 and (AX) indicate the error as follows. (AL) is the DOS
| |
| 4.00 error code that is the same as the error code returned in the low byte
| |
| of DI when an interrupt 24H is issued, and (AH) contains:
| |
|
| |
| 80H Attachment failed to respond
| |
| 40H SEEK operation failed
| |
| 08H Bad CRC on diskette read
| |
| 04H Requested sector not found
| |
| 03H Write attempt on write-protected diskette
| |
| 02H Error other than types listed above
| |
|
| |
| WARNING: BEFORE ISSUING THIS INTERRUPT TO REMOVABLE MEDIA, THE MEDIA IN THE
| |
| DRIVE MUST BE ESTABLISHED CORRECTLY. THIS CAN BE ACCOMPLISHED BY ISSUING
| |
| EITHER AN INT 21H GENERIC IOCTL (AH=44H), WITH A REQUEST TO RETURN THE BPB
| |
| THAT BUILD BPB RETURNS; OR AN INT 21H GET CURRENT DIRECTORY (AH=47H).
| |
|
| |
| 27H TERMINATE BUT STAY RESIDENT
| |
|
| |
| This vector is used by programs that are to remain resident when COMMAND.COM
| |
| regains control.
| |
|
| |
| DOS 4.00 function call 31H is the preferred method to cause a program to
| |
| remain resident, because this allows return information to be passed. It
| |
| allows a program larger than 64KB to remain resident. After initializing
| |
| itself, the program must set DX to its last address plus one, relative to the
| |
| program's initial DS or ES value (the offset at which other programs can be
| |
| loaded), and then execute an interrupt 27H. DOS 4.00 then considers the
| |
| program as an extension of itself, so the program is not overlaid when other
| |
| programs are executed. This concept is useful for loading programs such as
| |
| user-written interrupt handlers that must remain resident.
| |
|
| |
| NOTES:
| |
|
| |
| 1. This interrupt must not be used by .EXE programs that are loaded into the
| |
| high end of memory.
| |
|
| |
| 2. This interrupt restores the interrupt 22H, 23H, and 24H vectors in the
| |
| same manner as interrupt 20H. Therefore, it cannot be used to install
| |
| permanently resident Ctrl-Break or critical error handler routines.
| |
|
| |
| 3. The maximum size of memory that can be made resident by this method is
| |
| 64KB.
| |
|
| |
| 4. Memory can be used more efficiently if the block containing a copy of the
| |
| environment is deallocated before terminating. This can be done by
| |
| loading ES with the segment contained in 2C of the PSP, and issuing
| |
| function call 49H (Free Allocated Memory).
| |
|
| |
| 5. DOS 4.00 function call 4CH allows the terminating program to pass a
| |
| completion (or error) code to DOS 4.00, which can be interpreted within
| |
| batch processing (see function call 31H).
| |
|
| |
| 6. Terminate-but-stay-resident function calls do not automatically close
| |
| files.
| |
|
| |
| 28H-2EH RESERVED FOR DOS 4.00
| |
|
| |
| These interrupts are reserved for DOS 4.00 use.
| |
|
| |
| 2FH MULTIPLEX INTERRUPT
| |
|
| |
| Interrupt 2FH is the multiplex interrupt. A general interface is defined
| |
| between two processes. The specific application using interrupt 2FH defines
| |
| specific functions and parameters.
| |
|
| |
| Every multiplex interrupt handler is assigned a specific multiplex number.
| |
| The multiplex number is specified in the AH register. The specific function
| |
| that the handler is to perform is specified in the AL register. Other
| |
| parameters are placed in the other registers, as needed. The handlers are
| |
| chained into the interrupt 2FH interrupt vector. There is no defined method
| |
| for assigning a multiplex number to a handler. You must pick one. To avoid
| |
|
| |
| a conflict if two applications choose the same multiplex number, the
| |
| multiplex numbers used by an application should be patchable.
| |
|
| |
| The multiplex numbers AH=00H through BFH are reserved for DOS 4.00.
| |
| Applications should use multiplex numbers C0H through FFH.
| |
|
| |
| NOTE: When in the chain for interrupt 2FH, if your code calls DOS 4.00 or if
| |
| you execute with interrupts enabled, your code must be reentrant and
| |
| recursive.
| |
|
| |
| Function Codes
| |
|
| |
| AH=1
| |
|
| |
| AH=1 is the resident part of PRINT.
| |
|
| |
| The following table contains the function codes that you can specify in AL to
| |
| request the resident portion of print to perform a specific function:
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FUNCTION |
| |
| | CODES DESCRIPTION |
| |
| +---------------------------------------------------------------------------+
| |
| | 0 Get installed state |
| |
| +---------------------------------------------------------------------------+
| |
| | 1 Submit file |
| |
| +---------------------------------------------------------------------------+
| |
| | 2 Cancel file |
| |
| +---------------------------------------------------------------------------+
| |
| | 3 Cancel all files |
| |
| +---------------------------------------------------------------------------+
| |
| | 4 Status |
| |
| +---------------------------------------------------------------------------+
| |
| | 5 End of status |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| Print Error Codes
| |
|
| |
| The following table contains the error codes that are returned from the
| |
| resident portion of print.
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | ERROR |
| |
| | CODES DESCRIPTION |
| |
| +---------------------------------------------------------------------------+
| |
| | 1 Invalid function |
| |
| +---------------------------------------------------------------------------+
| |
| | 2 File not found |
| |
| +---------------------------------------------------------------------------+
| |
| | 3 Path not found |
| |
| +---------------------------------------------------------------------------+
| |
| | 4 Too many open files |
| |
| +---------------------------------------------------------------------------+
| |
| | 5 Access denied |
| |
| +---------------------------------------------------------------------------+
| |
| | 6 Queue full |
| |
| +---------------------------------------------------------------------------+
| |
| | 9 Busy |
| |
| +---------------------------------------------------------------------------+
| |
| | 12 Name too long |
| |
| +---------------------------------------------------------------------------+
| |
| | 15 Invalid drive |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| AL=0 Get Installed State
| |
|
| |
| This call must be defined by all interrupt 2FH handlers. It is used by the
| |
| caller of the handler to determine if the handler is present. On entry,
| |
| AL=0, AH=1. On return, AL contains the installed state as follows:
| |
|
| |
| AL=0 Not installed, permissible to install
| |
|
| |
| AL=1 Not installed, not permissible to install
| |
|
| |
| AL=FF Installed
| |
|
| |
| AL=1 Submit File
| |
|
| |
| On entry, AL=1, AH=1, and DS:DX points to the submit packet. A submit packet
| |
| contains the level (BYTE) and a pointer to the ASCIIZ string (DWORD in offset
| |
| segment form). The level value for DOS 4.00 is 0. The ASCIIZ string must
| |
| contain the drive, path, and filename of the file you want to print. The
| |
| filename cannot contain global filename characters. AL=2 Cancel File
| |
|
| |
| On entry, AL=2, AH=1, and DS:DX points to the ASCIIZ string for the print
| |
| file you want to cancel. Global filename characters are allowed in the
| |
| filename. AL=3 Cancel all Files
| |
|
| |
| On entry, AL=3 and AH=1.
| |
|
| |
| AL=4 Status
| |
|
| |
| This call holds the jobs in the print queue so that you can scan the queue.
| |
| Issuing any other code releases the jobs. On entry, AL=4, AH=1. On return,
| |
| DX contains the error count. The error count is the number of consecutive
| |
| failures PRINT had while trying to output the last character. If there are
| |
| no failures, the number is 0. DS:SI points to the print queue. The print
| |
| queue consists of a series of filename entries. Each entry is 64 bytes long.
| |
| The first entry in the queue is the file currently being printed. The end of
| |
| the queue is marked by a queue entry having a null as the first character.
| |
|
| |
| AL=5 End of Status: Issue this call to release the queue from call 4. On
| |
| entry, AL=5 and AH=1. On return, AX contains the error codes. For
| |
| information on the error codes returned, refer to "Print Error Codes" on
| |
| page A-10.
| |
|
| |
| AL=F8-FF Reserved by DOS 4.00
| |
|
| |
| AH=6
| |
|
| |
| AH=6 is the resident part of ASSIGN.
| |
| The Get Installed State function
| |
| (AL=0) is supported.
| |
|
| |
| AH=8H, 10H, 12H, 13H Reserved by DOS 4.00
| |
|
| |
| AH=B7H
| |
|
| |
| AH=B7H is the resident part of APPEND.
| |
| The Get Installed State function
| |
| (AL=0) is supported.
| |
|
| |
| AL=2 Get APPEND version
| |
| This call is for distinguishing between
| |
| the PC LAN APPEND and the DOS 4.00 APPEND.
| |
| On return, if AX=FFFFH then the DOS 4.00
| |
| APPEND is loaded.
| |
|
| |
| AL=4 Get APPEND Path Pointer
| |
| (DOS 4.00 APPEND only)
| |
| On return ES:DI points to the
| |
| currently active APPEND path.
| |
|
| |
| AL=6 Get APPEND Function State
| |
| (DOS 4.00 APPEND only)
| |
|
| |
| BX is returned with bits set indicating
| |
| if APPEND is currently enabled and what
| |
| functions are in effect.
| |
|
| |
| +--------+------------------------------------------------------------------+
| |
| | BIT | FUNCTION IN EFFECT IF BIT IS ON |
| |
| +--------+------------------------------------------------------------------+
| |
| | 0 | APPEND enabled |
| |
| +--------+------------------------------------------------------------------+
| |
| | 13 | /PATH |
| |
| +--------+------------------------------------------------------------------+
| |
| | 14 | /E |
| |
| +--------+------------------------------------------------------------------+
| |
| | 15 | /X |
| |
| +--------+------------------------------------------------------------------+
| |
|
| |
| NOTE: The functions in effect do not change whether or not APPEND is
| |
| disabled.
| |
|
| |
| AL=7 Set function state (DOS 4.00 APPEND
| |
| only)
| |
|
| |
| On input BX is the new setting for all functions.
| |
| The suggested procedure is to get the current function
| |
| state, turn on or turn off the desired bits, then
| |
| use this call to set the function state.
| |
|
| |
| AL=11H Set Return Found Name State (DOS 4.00 APPEND
| |
| only)
| |
|
| |
| On request AL=17, a process system state flag is set. If this flag is set,
| |
| then on the next ASCIIZ 3DH, 43H or 6CH function call within Interrupt 21H
| |
| that APPEND processes, APPEND returns the name it finds to the application
| |
| filename buffer. This name may be different from the one the application
| |
| offered. The application must provide enough space for the found name.
| |
| After APPEND has processed an
| |
|
| |
| Interrupt 21H, it resets the Return Found Name state. An example of this
| |
| process follows:
| |
|
| |
| MOV AH,0B7H ; Indicate APPEND
| |
| MOV AL,0 ; Get installed state
| |
| INT 2FH
| |
| CMP AL,0 ; APPEND installed?
| |
| JE NOT_INSTALLED
| |
|
| |
| MOV AH,0B7H ; Indicate APPEND
| |
| MOV AL,2 ; Get APPEND version
| |
| INT 2FH
| |
| CMP AX,-1 ; DOS version?
| |
| PC_LAN_APPEND ; AX<> -1 means PC LAN
| |
| JNE
| |
| APPEND
| |
|
| |
| ; The following functions are valid only if DOS 4.00 APPEND
| |
|
| |
| MOV AH,0B7H ; Indicate APPEND
| |
| MOV AL,4 ; Get APPEND path pointer
| |
| INT 2FH
| |
|
| |
| ; ES:DI = address of APPEND path
| |
| ; (Buffer is 128 characters long)
| |
|
| |
| MOV AH,0B7H ; Indicate APPEND
| |
| MOV AL,6 ; Get function state
| |
| INT 2FH
| |
| ; BX = function state
| |
| ; 8000H = /X is on
| |
| ; 4000H = /E is on
| |
| ; 2000H = /PATH is on
| |
| ; 0001H = APPEND enabled
| |
| ; If off, similar to null
| |
| ; APPEND path
| |
| ; Set on by any non-status
| |
| ; occurrence of APPEND
| |
|
| |
| MOV AH,0B7H ; Indicate APPEND
| |
| MOV AL,7 ; Set function state
| |
| MOV BX,state ; New state
| |
| INT 2FH
| |
|
| |
| MOV AH,0B7H ; Indicate APPEND
| |
| MOV AL,11H ; Set Return Found
| |
| ; Name state
| |
| INT 2FH
| |
|
| |
| Example 2FH Handler
| |
|
| |
| MYNUM DB X ; X = The specific AH
| |
| ; multiplex number.
| |
| INT 2F NEXT DD ? ; Chain location
| |
| INT 2F:
| |
|
| |
| ASSUME DS:NOTHING,ES:NOTHING,SS:NOTHING
| |
|
| |
| CMP AH,MYNUM
| |
| JE MINE
| |
| JMP INT 2F NEXT ; Chain to next
| |
| ; 2FH Handler
| |
|
| |
| MINE:
| |
|
| |
| CMP AL,0F8H
| |
| JB DO FUNC
| |
| IRET ; IRET on reserved
| |
| ; functions
| |
|
| |
| DO FUNC:
| |
|
| |
| OR AL,AL
| |
| JNE NON INSTALL ; Non Get Installed
| |
| ; State request
| |
| MOV AL,0FFH ; Say I'm here
| |
| IRET ; All done
| |
|
| |
| NON INSTALL:
| |
| .
| |
| .
| |
| .
| |
|
| |
| Installing the Handler
| |
|
| |
| The following example contains the functions necessary to install a handler:
| |
|
| |
| MOV AH,MYNUM
| |
| XOR AL,AL
| |
| INT 2FH ; Ask if already
| |
| ; installed
| |
| OR AL,AL
| |
| JZ OK INSTALL
| |
|
| |
| BAD INSTALL: ; Handler already installed .sp 3
| |
| OK INSTALL: ; Install my
| |
| ; handler
| |
|
| |
| MOV AL,2FH
| |
| MOV AH,GET INTERRUPT VECTOR
| |
| INT 21H ; Get multiplex
| |
| ; vector
| |
| MOV WORD PTR INT 2F NEXT+2,ES
| |
| MOV WORD PTR INT 2F NEXT,BX
| |
| MOV DX,OFFSET INT 2F
| |
| MOV AL,2FH
| |
| MOV AH,SET INTERRUPT VECTOR
| |
| INT 21H ; Set multiplex
| |
| ; vector
| |
| .
| |
| .
| |
| .
| |
|
| |
| 30H-3FH RESERVED FOR DOS 4.00
| |
|
| |
| These interrupts are reserved for DOS 4.00 use.
| |
| | |
| </PRE>
| |
| | |
| ==Appendix B==
| |
| <PRE>
| |
| APPENDIX B. DOS 4.00 FUNCTION CALLS 100
| |
| Using DOS 4.00 Function Calls 219
| |
| Program Code Fragments 230
| |
| .COM Programs 236
| |
| DOS 4.00 Registers 256
| |
| Responding to Errors 340
| |
| Extended Error Codes 355
| |
| 00H -- Program Terminate 518
| |
| 01H -- Console Input with Echo 546
| |
| 02H -- Display Output 581
| |
| 03H -- Auxiliary Input 603
| |
| 04H -- Auxiliary Output 631
| |
| 05H -- Printer Output 655
| |
| 06H -- Direct Console I/O 672
| |
| 07H -- Direct Console Input Without Echo 720
| |
| 08H -- Console Input Without Echo 753
| |
| 09H -- Display String 786
| |
| 0AH -- Buffered Keyboard Input 815
| |
| 0BH -- Check Standard Input Status 848
| |
| 0CH -- Clear Keyboard Buffer and Invoke a Keyboard Function 868
| |
| 0DH -- Disk Reset 885
| |
| 0EH -- Select Disk 904
| |
| 0FH -- Open File 937
| |
| 10H -- Close File 985
| |
| 11H -- Search for First Entry 1022
| |
| 12H -- Search for Next Entry 1099
| |
| 13H -- Delete File 1149
| |
| 14H -- Sequential Read 1193
| |
| 15H -- Sequential Write 1240
| |
| 16H -- Create File 1286
| |
| 17H -- Rename File 1330
| |
| 19H -- Current Disk 1380
| |
| 1AH -- Set Disk Transfer Address 1400
| |
| 1BH -- Allocation Table Information 1425
| |
| 1CH -- Allocation Table Information for Specific Device 1453
| |
| 21H -- Random Read 1489
| |
| 22H -- Random Write 1541
| |
| 23H -- File Size 1599
| |
| 24H -- Set Relative Record Field 1642
| |
| 25H -- Set Interrupt Vector 1668
| |
| 26H -- Create New Program Segment 1695
| |
| 27H -- Random Block Read 1725
| |
| 28H -- Random Block Write 1787
| |
| 29H -- Parse Filename 1847
| |
| 2AH -- Get Date 1918
| |
| 2BH -- Set Date 1946
| |
| 2CH -- Get Time 1979
| |
| 2DH -- Set Time 2015
| |
| 2EH -- Set/Reset Verify Switch 2051
| |
| 2FH -- Get Disk Transfer Address (DTA) 2085
| |
| 30H -- Get DOS Version Number 2108
| |
| 31H -- Terminate Process and Remain Resident 2138
| |
| 33H -- Get/Set System Value 2175
| |
| 35H -- Get Interrupt Vector 2235
| |
| 36H -- Get Disk Free Space 2262
| |
| 38H -- Get or Set Country Dependent Information 2318
| |
| 39H -- Create Subdirectory (MKDIR) 2431
| |
| 3AH -- Remove Subdirectory (RMDIR) 2466
| |
| 3BH -- Change the Current Directory (CHDIR) 2498
| |
| 3CH -- Create a File (CREAT) 2530
| |
| 3DH -- Open a File 2577
| |
| 3EH -- Close a File Handle 2812
| |
| 3FH -- Read from a File or Device 2840
| |
| 40H -- Write to a File or Device 2886
| |
| 41H -- Delete a File from a Specified Directory (UNLINK) 2938
| |
| 42H -- Move File Read Write Pointer (LSEEK) 2971
| |
| 43H -- Change File Mode (CHMOD) 3035
| |
| 44H -- I/O Control for Devices 3092
| |
| 45H -- Duplicate a File Handle (DUP) 3103
| |
| 46H -- Force a Duplicate of a Handle (FORCDUP) 3137
| |
| 47H -- Get Current Directory 3170
| |
| 48H -- Allocate Memory 3202
| |
| 49H -- Free Allocated Memory 3237
| |
| 4AH -- Modify Allocated Memory Blocks (SETBLOCK) 3263
| |
| 4BH -- Load or Execute a Program (EXEC) 3303
| |
| 4CH -- Terminate a Process (EXIT) 3442
| |
| 4DH -- Get Return Code of a Subprocess (WAIT) 3466
| |
| 4EH -- Find First Matching File (FIND FIRST) 3494
| |
| 4FH -- Find Next Matching File (FIND NEXT) 3567
| |
| 54H -- Get Verify Setting 3606
| |
| 56H -- Rename a File 3628
| |
| 57H -- Get/Set File's Date and Time 3669
| |
| 59H -- Get Extended Error 3714
| |
| 5AH -- Create Unique File 3785
| |
| 5BH -- Create New File 3839
| |
| 5CH -- Lock/Unlock File Access 3878
| |
| 5E00H -- Get Machine Name 3972
| |
| 5E02H -- Set Printer Setup 4006
| |
| 5E03H -- Get Printer Setup 4051
| |
| 5F02H -- Get Redirection List Entry 4096
| |
| 5F03H -- Redirect Device 4169
| |
| 5F04H -- Cancel Redirection 4259
| |
| 62H -- Get Program Segment Prefix Address 4305
| |
| 65H -- Get Extended Country Information 4328
| |
| 66H -- Get/Set Global Code Page 4451
| |
| 67H -- Set Handle Count 4494
| |
| 68H -- Commit File 4539
| |
| 6CH -- Extended Open/Create 4562
| |
|
| |
| APPENDIX B. DOS 4.00 FUNCTION CALLS
| |
|
| |
| NUMBER FUNCTION NAME
| |
| 00H Program terminate
| |
| 01H Console input with echo
| |
| 02H Display output
| |
| 03H Auxiliary input
| |
| 04H Auxiliary output
| |
| 05H Printer output
| |
| 06H Direct console I/O
| |
| 07H Direct console input without echo
| |
| 08H Console input without echo
| |
| 09H Display string
| |
| 0AH Buffered keyboard input
| |
| 0BH Check standard input status
| |
| 0CH Clear keyboard buffer, invoke a keyboard function
| |
| 0DH Disk reset
| |
| 0EH Select disk
| |
| 0FH Open file
| |
| 10H Close file
| |
| 11H Search for first entry
| |
| 12H Search for next entry
| |
| 13H Delete file
| |
| 14H Sequential read
| |
| 15H Sequential write
| |
| 16H Create file
| |
| 17H Rename file
| |
| 18H Reserved by DOS 4.00
| |
| 19H Current disk
| |
| 1AH Set disk transfer address
| |
| 1BH Allocation table information
| |
| 1CH Allocation table information for specific device
| |
| 1DH Reserved by DOS 4.00
| |
| 1EH Reserved by DOS 4.00
| |
| 1FH Reserved by DOS 4.00
| |
| 20H Reserved by DOS 4.00
| |
| 21H Random read
| |
| 22H Random write
| |
| 23H File size
| |
| 24H Set relative record field
| |
| 25H Set interrupt vector
| |
| 26H Create new program segment
| |
| 27H Random block read
| |
| 28H Random block write
| |
| 29H Parse filename
| |
| 2AH Get date
| |
| 2BH Set date
| |
| 2CH Get time
| |
| 2DH Set time
| |
| 2EH Set/reset verify switch
| |
| 2FH Get disk transfer address
| |
| 30H Get DOS 4.00 version number
| |
| 31H Terminate process and remain resident
| |
|
| |
| 32H Reserved by DOS 4.00
| |
| 33H Get/Set system value
| |
| 34H Reserved by DOS 4.00
| |
| 35H Get interrupt vector
| |
| 36H Get disk free space
| |
| 37H Reserved by DOS 4.00
| |
| 38H Get/set country dependent information
| |
| 39H Create subdirectory (MKDIR)
| |
| 3AH Remove subdirectory (RMDIR)
| |
| 3BH Change current directory (CHDIR)
| |
| 3CH Create a file (CREAT)
| |
| 3DH Open a file
| |
| 3EH Close a file handle
| |
| 3FH Read from a file or device
| |
| 40H Write to a file or device
| |
| 41H Delete a file from a specified directory (UNLINK)
| |
| 42H Move file read/write pointer (LSEEK)
| |
| 43H Change file mode (CHMOD)
| |
| 44H I/O control for devices (IOCtl)
| |
| 45H Duplicate a file handle (DUP)
| |
| 46H Force a duplicate of a file handle (FORCDUP)
| |
| 47H Get current directory
| |
| 48H Allocate memory
| |
| 49H Free allocated memory
| |
| 4AH Modify allocated memory blocks (SETBLOCK)
| |
| 4BH Load or execute a program (EXEC)
| |
| 4CH Terminate a process (EXIT)
| |
| 4DH Get return code of a subprocess (WAIT)
| |
| 4EH Find first matching file (FIND FIRST)
| |
| 4FH Find next matching file (FIND NEXT)
| |
| 50H Reserved by DOS 4.00
| |
| 51H Reserved by DOS 4.00
| |
| 52H Reserved by DOS 4.00
| |
| 53H Reserved by DOS 4.00
| |
| 54H Get verify setting
| |
| 55H Reserved by DOS 4.00
| |
| 56H Rename a file
| |
| 57H Get/set a file's date and time
| |
| 58H Reserved for DOS 4.00
| |
| 59H Get extended error
| |
| 5AH Create unique file
| |
| 5BH Create new file
| |
| 5CH Lock/unlock file access
| |
| 5DH Reserved by DOS 4.00
| |
| 5E00H Get machine name
| |
| 5E02H Set printer setup
| |
| 5E03H Get printer setup
| |
| 5F02H Get redirection list entry
| |
| 5F03H Redirect device
| |
| 5F04H Cancel redirection
| |
| 60H Reserved by DOS 4.00
| |
| 61H Reserved by DOS 4.00
| |
| 62H Get PSP address
| |
| 63H Reserved by DOS 4.00
| |
| 64H Reserved by DOS 4.00
| |
| 65H Get extended country information
| |
| 66H Get/set global code page
| |
|
| |
| 67H Set handle count
| |
| 68H Commit file
| |
| 69H Reserved by DOS 4.00
| |
| 6AH Reserved
| |
| 6BH Reserved by DOS 4.00
| |
| 6CH Extended open/create
| |
|
| |
| USING DOS 4.00 FUNCTION CALLS
| |
|
| |
| Most function calls require input to be passed to them in registers. After
| |
| setting the appropriate register values, issue the function calls in either
| |
| of the following ways:
| |
|
| |
| The preferred method is to place the function number in AH and issue
| |
| interrupt 21H.
| |
| Place the function number in AH and execute a call to offset 50H in your
| |
| program segment prefix.
| |
|
| |
| PROGRAM CODE FRAGMENTS
| |
|
| |
| In each of the function call descriptions in this chapter, the input, output
| |
| and method of use are described using a small program code fragment. These
| |
| fragments are written in IBM PC Assembler Language.
| |
|
| |
| .COM PROGRAMS
| |
|
| |
| The descriptions assume that the program is an .EXE, not a .COM program. If
| |
| a .COM program is desired, do not include either of the following
| |
| instructions:
| |
|
| |
| MOV ES,SEG --
| |
| or
| |
| MOV DS,SEG --
| |
|
| |
| NOTES:
| |
|
| |
| 1. Some FCB function calls do not permit invalid characters (0DH-29H).
| |
|
| |
| 2. Device names cannot end in a colon.
| |
|
| |
| 3. The contents of the AX register can be altered by any of the function
| |
| calls. Even though no error code is returned in AX, it is possible that
| |
| AX has been changed.
| |
|
| |
| DOS 4.00 REGISTERS
| |
|
| |
| DOS 4.00 uses the following registers, pointers, and flags when executing
| |
| interrupts and function calls:
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | REGISTER GENERAL |
| |
| | DEFINITION REGISTERS |
| |
| +---------------------------------------------------------------------------+
| |
| | AX Accumulator (16-bit) |
| |
| | AH Accumulator high-order byte (8-bit) |
| |
| | AL Accumulator low-order byte (8-bit) |
| |
| +---------------------------------------------------------------------------+
| |
| | BX Base (16-bit) |
| |
| | BH Base high-order byte (8-bit) |
| |
| | BL Base low-order byte (8-bit) |
| |
| +---------------------------------------------------------------------------+
| |
| | CX Count (16-bit) |
| |
| | CH Count high-order byte (8-bit) |
| |
| | CL Count low-order byte (8-bit) |
| |
| +---------------------------------------------------------------------------+
| |
| | DX Data (16-bit) |
| |
| | DH Data high-order (8-bit) |
| |
| | DL Data low-order (8-bit) |
| |
| +---------------------------------------------------------------------------+
| |
| | Flags OF,DF,IF,TF,SF,ZF,AF,PF,CF |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | REGISTER |
| |
| | DEFINITION POINTERS |
| |
| +---------------------------------------------------------------------------+
| |
| | SP Stack pointer (16-bit) |
| |
| +---------------------------------------------------------------------------+
| |
| | BP Base pointer (16-bit) |
| |
| +---------------------------------------------------------------------------+
| |
| | IP Instruction pointer (16-bit) |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | REGISTER SEGMENT |
| |
| | DEFINITION REGISTERS |
| |
| +---------------------------------------------------------------------------+
| |
| | CS Code segment (16-bit) |
| |
| +---------------------------------------------------------------------------+
| |
| | DS Data segment (16-bit) |
| |
| +---------------------------------------------------------------------------+
| |
| | SS Stack segment (16-bit) |
| |
| +---------------------------------------------------------------------------+
| |
| | ES Extra segment (16-bit) |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | REGISTER INDEX |
| |
| | DEFINITION REGISTERS |
| |
| +---------------------------------------------------------------------------+
| |
| | DI Destination index (16-bit) |
| |
| +---------------------------------------------------------------------------+
| |
| | SI Source index (16-bit) |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| Register Numbering Convention
| |
|
| |
| Each register is 16 bits long and is divided into a high and low byte. Each
| |
| byte is 8 bits long. The bits are numbered from right to left. The low byte
| |
| contains bits 0 through 7 and the high byte contains bits 8 through 15. The
| |
| chart below shows the hexadecimal values assigned to each bit.
| |
|
| |
| +--------------------------------------------------------------------------+
| |
| | High Byte Low Byte |
| |
| +--------------------------------------------------------------------------+
| |
| | Bit 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 |
| |
| +--------------------------------------------------------------------------+
| |
| | Hex value 8 4 2 1 8 4 2 1 8 4 2 1 8 4 2 1 |
| |
| +--------------------------------------------------------------------------+
| |
|
| |
| DOS 4.00 Internal Stack
| |
|
| |
| When DOS 4.00 gains control, it switches to an internal stack. User
| |
| registers are preserved unless information is passed back to the requester as
| |
| indicated in the specific requests. The user stack needs to be sufficient to
| |
| accommodate the interrupt system. It is recommended that the user stack be
| |
| 200H in addition to what the user needs.
| |
|
| |
| RESPONDING TO ERRORS
| |
|
| |
| Handle function calls report an error by setting the carry flag and returning
| |
| the error code in AX. FCB function calls report an error by returning FFH in
| |
| AL.
| |
|
| |
| Extended error support (59H) provides a common set of error codes and
| |
| specific error information such as error classification, location, and
| |
| recommended action. In most critical cases, applications can analyze the
| |
| error code and take specific action. Recommended actions are intended for
| |
| programs that do not understand the error codes. Programs can take advantage
| |
| of extended error support both from interrupt 24H critical error handlers and
| |
| after issuing interrupt 21H function calls. Do not code to specific error
| |
| codes.
| |
|
| |
| EXTENDED ERROR CODES
| |
|
| |
| HEXADECIMAL DECIMAL
| |
| CODE CODE MEANING
| |
| 01H 1 Invalid function number
| |
| 02H 2 File not found
| |
| 03H 3 Path not found
| |
| 04H 4 Too many open files (no handles left)
| |
| 05H 5 Access denied
| |
| 06H 6 Invalid handle
| |
| 07H 7 Memory control blocks destroyed
| |
| 08H 8 Insufficient memory
| |
| 09H 9 Invalid memory block address
| |
| 0AH 10 Invalid environment
| |
| 0BH 11 Invalid format
| |
| 0CH 12 Invalid access code
| |
| 0DH 13 Invalid data
| |
| 0EH 14 Reserved
| |
| 0FH 15 Invalid drive was specified
| |
| 10H 16 Attempt to remove the current directory
| |
| 11H 17 Not same device
| |
| 12H 18 No more files
| |
| 13H 19 Attempt to write on write-protected diskette
| |
| 14H 20 Unknown unit
| |
| 15H 21 Drive not ready
| |
| 16H 22 Unknown command
| |
| 17H 23 Cyclic redundancy check (CRC) -- part of diskette
| |
| is bad
| |
| 18H 24 Bad request structure length
| |
| 19H 25 Seek error
| |
| 1AH 26 Unknown media type
| |
| 1BH 27 Sector not found
| |
| 1CH 28 Printer out of paper
| |
| 1DH 29 Write fault
| |
| 1EH 30 Read fault
| |
| 1FH 31 General failure
| |
| 20H 32 Sharing violation
| |
| 21H 33 Lock violation
| |
| 22H 34 Invalid disk change
| |
| 23H 35 FCB unavailable
| |
| 24H 36 Sharing buffer overflow
| |
| 25H 37 Reserved by DOS 4.00
| |
| 26H 38 Unable to complete file operation
| |
| 27H-31H 39-49 Reserved by DOS 4.00
| |
| 50H 80 File exists
| |
| 51H 81 Reserved
| |
| 52H 82 Cannot make directory entry
| |
| 53H 83 Fail on INT 24
| |
| 54H 84 Too many redirections
| |
| 55H 85 Duplicate redirection
| |
| 56H 86 Invalid password
| |
| 57H 87 Invalid parameter
| |
| 58H 88 Network data fault
| |
| 59H 89 Function not supported by network
| |
|
| |
| HEXADECIMAL DECIMAL
| |
| CODE CODE MEANING
| |
| 5AH 90 Required system component not installed
| |
|
| |
| Extended Error Codes
| |
|
| |
| HEXADECIMAL DECIMAL
| |
| CODE CODE MEANING
| |
| 32H 50 Network request not supported
| |
| 33H 51 Remote computer not listening
| |
| 34H 52 Duplicate name on network
| |
| 35H 53 Network path not found
| |
| 36H 54 Network busy
| |
| 37H 55 Network device no longer exists
| |
| 38H 56 NETBIOS command limit exceeded
| |
| 39H 57 System error; NETBIOS error
| |
| 3AH 58 Incorrect response from network
| |
| 3BH 59 Unexpected network error
| |
| 3CH 60 Incompatible remote adapter
| |
| 3DH 61 Print queue full
| |
| 3EH 62 Not enough space for print file
| |
| 3FH 63 Print file was cancelled
| |
| 40H 64 Network name was deleted
| |
| 41H 65 Access denied
| |
| 42H 66 Network device type incorrect
| |
| 43H 67 Network name not found
| |
| 44H 68 Network name limit exceeded
| |
| 45H 69 NETBIOS session limit exceeded
| |
| 46H 70 Sharing temporarily paused
| |
| 47H 71 Network request not accepted
| |
| 48H 72 Print or disk redirection is paused
| |
| 49H-4FH 73-79 Reserved
| |
|
| |
| Error Classes
| |
|
| |
| HEXADECIMAL DECIMAL
| |
| VALUE VALUE DESCRIPTION
| |
| 01H 1 OUT OF RESOURCE: Example: out of space or
| |
| channels.
| |
| 02H 2 TEMPORARY SITUATION: Something expected to
| |
| disappear with time. This is not an error
| |
| condition, but a temporary situation such as a
| |
| locked file.
| |
| 03H 3 AUTHORIZATION: Permission problem.
| |
| 04H 4 INTERNAL: Internal error in system software.
| |
| Probable problem with system software rather than a
| |
| user or system failure.
| |
|
| |
| HEXADECIMAL DECIMAL
| |
| VALUE VALUE DESCRIPTION
| |
| 05H 5 HARDWARE FAILURE: A serious problem not the fault
| |
| of user program.
| |
| 06H 6 SYSTEM FAILURE: Serious failure of system software
| |
| not the fault of the user, such as missing or
| |
| incorrect configuration files.
| |
| 07H 7 APPLICATION PROGRAM ERROR: Inconsistent requests.
| |
| 08H 8 NOT FOUND: File or item not found. Inconsistent
| |
| requests.
| |
| 09H 9 BAD FORMAT: File or value in invalid format or
| |
| type; unsuitable.
| |
| 0AH 10 LOCKED: Locked file or item.
| |
| 0BH 11 MEDIA: Media failure such as incorrect disk, CRC
| |
| error, or defective media.
| |
| 0CH 12 ALREADY EXISTS: Duplication error, such as
| |
| declaring a machine name that already exists.
| |
| 0DH 13 UNKNOWN: Classification does not exist or is
| |
| inappropriate.
| |
|
| |
| Actions
| |
|
| |
| HEXADECIMAL DECIMAL
| |
| CODE CODE DESCRIPTION
| |
| 01H 1 RETRY: Retry a few times, then prompt user to
| |
| determine if the program should continue or be
| |
| terminated.
| |
| 02H 2 DELAY RETRY: Retry several times after pause, then
| |
| prompt user to determine if the program should
| |
| continue or be terminated.
| |
| 03H 3 USER: If the input was entered by a user, advise
| |
| reentry. The error, however, may have occurred in
| |
| the program itself, such as a bad drive letter or
| |
| bad filename specification.
| |
| 04H 4 ABORT: Abort application with cleanup. The
| |
| application cannot proceed, but the system is in an
| |
| orderly state and it is safe to stop the
| |
| application.
| |
| 05H 5 IMMEDIATE EXIT: Stop application immediately
| |
| without clearing registers. Do not use the
| |
| application to close files or update indexes, but
| |
| exit as soon as possible.
| |
| 06H 6 IGNORE: Ignore.
| |
| 07H 7 RETRY AFTER USER INTERVENTION: The user needs to
| |
| perform some action such as removing a diskette and
| |
| inserting a different one. Then retry the
| |
| operation.
| |
|
| |
| Locus (Location)
| |
|
| |
| HEXADECIMAL DECIMAL
| |
| VALUE VALUE DESCRIPTION
| |
| 01H 1 UNKNOWN: Not specific; not appropriate.
| |
| 02H 2 BLOCK DEVICE: Related to random access mass disk
| |
| storage.
| |
| 03H 3 NET: Related to the network.
| |
| 04H 4 SERIAL DEVICE: Related to serial devices.
| |
| 05H 5 MEMORY: Related to random access memory.
| |
|
| |
| 00H --
| |
| PROGRAM TERMINATE
| |
|
| |
| PURPOSE
| |
|
| |
| Stops the execution of a program.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,00H ; Function Call -- Terminate Program
| |
| INT 21H ; Issue request to DOS
| |
| ; No return
| |
|
| |
| COMMENTS
| |
|
| |
| The terminate, Ctrl-Break, and critical error exit addresses are restored to
| |
| the values they had on entry to the terminating program, from the values
| |
| saved in the program segment prefix. All file buffers are flushed and the
| |
| handles opened by the process are closed. Any files that have changed in
| |
| length and not closed are not recorded properly in the directory. Control
| |
| transfers to the terminate address. This call performs exactly the same
| |
| function as interrupt 20H. It is the program's responsibility to ensure that
| |
| the CS register contains the segment address of its program segment prefix
| |
| control block before calling this function.
| |
|
| |
| Function 4CH -- Terminate a Process is the preferred method for ending a
| |
| program.
| |
|
| |
| 01H --
| |
| CONSOLE INPUT WITH ECHO
| |
|
| |
| PURPOSE
| |
|
| |
| Waits for a character to be read at the standard input device (unless one is
| |
| ready), then echoes the character to the standard output device and returns
| |
| the character in AL.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,01H ; Function Call -- keyboard input
| |
| INT 21H ; Issue request to DOS
| |
| MOV Char,AL ; Save character
| |
| CMP AL,0 ; Extended character ?
| |
| JNE Normal Char ; No!
| |
| MOV AH,01H ; Function Call -- keyboard input
| |
| INT 21H ; Issue request to DOS
| |
| MOV ExtChar,AL ; Save extended character
| |
| Normal Char:
| |
|
| |
|
| |
| Character LABEL WORD ; Complete character
| |
| Char DB ? ; Character buffer
| |
| ExtChar DB ? ; Character buffer
| |
|
| |
| COMMENTS
| |
|
| |
| The character is checked for a Ctrl-Break. If Ctrl-Break is detected, an
| |
| interrupt 23H is executed.
| |
|
| |
| For function call 01H, extended ASCII codes require two function calls. The
| |
| first call returns 00H as an indicator that the next call will return an
| |
| extended code.
| |
|
| |
| 02H --
| |
| DISPLAY OUTPUT
| |
|
| |
| PURPOSE
| |
|
| |
| Outputs the character in DL to the standard output device.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,02H ; Function Call -- Display Output
| |
| MOV DL,Char ; Get character to display
| |
| INT 21H ; Issue request to DOS
| |
|
| |
|
| |
| CHAR DB ? ; Character buffer
| |
|
| |
| COMMENTS
| |
|
| |
| If the character in DL is a backspace (08), the cursor is moved left one
| |
| position (nondestructive). If a Ctrl-Break is detected after the output, an
| |
| interrupt 23H is executed.
| |
|
| |
| 03H --
| |
| AUXILIARY INPUT
| |
|
| |
| PURPOSE
| |
|
| |
| Waits for a character from the standard auxiliary device, then returns that
| |
| character in AL.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,03H ; Function Call -- Auxiliary Input
| |
| INT 21H ; Issue request to DOS
| |
| MOV Char,AL ; Save character
| |
|
| |
|
| |
| CHAR DB ? ; Character buffer
| |
|
| |
| COMMENTS
| |
|
| |
| Auxiliary (AUX) support is unbuffered and noninterrupt driven.
| |
|
| |
| At startup, DOS 4.00 initializes the first auxiliary port to 2400 baud, no
| |
| parity, one-stop bit, and 8-bit word.
| |
|
| |
| The auxiliary function calls (03H and 04H) do not return status or error
| |
| codes. For greater control, you should use the ROM BIOS routine (interrupt
| |
| 14H) or write an AUX device driver and use IOCtl.
| |
|
| |
| 04H --
| |
| AUXILIARY OUTPUT
| |
|
| |
| PURPOSE
| |
|
| |
| Outputs the character in DL to the standard auxiliary device.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,04H ; Function Call -- Auxiliary Output
| |
|
| |
| MOV DL,Char ; Get character to output
| |
| INT 21H ; Issue request to DOS
| |
| ; Nothing returned
| |
|
| |
|
| |
| CHAR DB ? ; Character buffer
| |
|
| |
| COMMENTS
| |
|
| |
| If the character in DL is a backspace (08), the cursor is moved left one
| |
| position (nondestructive). If a Ctrl-Break is detected after the output, an
| |
| interrupt 23H is executed.
| |
|
| |
| 05H --
| |
| PRINTER OUTPUT
| |
|
| |
| PURPOSE
| |
|
| |
| Outputs the character in DL to the standard printer device.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,05H ; Function Call -- Printer Output
| |
| MOV DL,Char ; Get character to output
| |
| INT 21H ; Issue request to DOS
| |
| ; Nothing returned
| |
|
| |
|
| |
| CHAR DB ? ; Character buffer
| |
|
| |
| 06H --
| |
| DIRECT CONSOLE I/O
| |
|
| |
| PURPOSE
| |
|
| |
| Gets a character from the standard input device if one is ready, or outputs a
| |
| character to the standard output device.
| |
|
| |
| EXAMPLES
| |
|
| |
| In loop:
| |
| MOV AH,06H ; Function Call -- Direct Console I/O
| |
| MOV DL,-1 ; 0FFH for input
| |
| INT 21H ; Issue request to DOS
| |
| JZ In loop ; No character yet on input
| |
| MOV Char,AL ; Save character
| |
| CMP AL,0 ; Extended Character ?
| |
| JNE Normal Char ; No!
| |
| MOV AH,07H ; Function Call -- Keyboard Input
| |
| INT 21H ; Issue request to DOS
| |
| MOV ExtChar,AL ; Save extended character
| |
| Normal Char:
| |
|
| |
| or
| |
|
| |
| MOV AH,06H ; Function Call -- Direct Console I/O
| |
| MOV DL,Char ; Get character to display (not 0FFH)
| |
| INT 21H ; Issue request to DOS
| |
|
| |
|
| |
| Character LABEL WORD ; Complete character
| |
| Char DB ? ; Character buffer
| |
| ExtChar DB ? ; Character buffer
| |
|
| |
| COMMENTS
| |
|
| |
| If DL is FFH, AL returns with the 0 flag clear and an input character from
| |
| the standard input device, if one is ready. If a character is not ready, the
| |
| 0 flag will be set.
| |
|
| |
| If DL is not FFH, DL is assumed to have a valid character that is output to
| |
| the standard output device. This function does not check for Ctrl-Break, or
| |
| Ctrl-PrtSc.
| |
|
| |
| For function call 06H, extended ASCII codes require two function calls. The
| |
| first call returns 00H as an indicator that the next call will return an
| |
| extended code.
| |
|
| |
| 07H --
| |
| DIRECT CONSOLE INPUT WITHOUT ECHO
| |
|
| |
| PURPOSE
| |
|
| |
| Waits for a character to be read at the standard input device (unless one is
| |
| ready), then returns the character in AL.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,07H ; Function Call -- Direct Console Input (no echo)
| |
| INT 21H ; Issue request to DOS
| |
| MOV Char,AL ; Save character
| |
| CMP AL,0 ; Extended character ?
| |
| JNE Normal Char ; No!
| |
| MOV AH,07H ; Function Call -- Direct Console Input (no echo)
| |
| INT 21H ; Issue request to DOS
| |
| MOV ExtChar,AL ; Save extended character
| |
| Normal Char:
| |
|
| |
|
| |
| Character LABEL WORD ; Complete character
| |
| Char DB ? ; Character buffer
| |
| ExtChar DB ? ; Character buffer
| |
|
| |
| COMMENTS
| |
|
| |
| As with function call 06H, no checks are made on the character.
| |
|
| |
| For function call 07H, extended ASCII codes require two function calls. The
| |
| first call returns 00H as an indicator that the next call will return an
| |
| extended code.
| |
|
| |
| 08H --
| |
| CONSOLE INPUT WITHOUT ECHO
| |
|
| |
| PURPOSE
| |
|
| |
| Waits for a character to be read at the standard input device (unless one is
| |
| ready) and returns the character in AL.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,08H ; Function Call -- Console Input (no echo)
| |
| INT 21H ; Issue request to DOS
| |
| MOV Char,AL ; Save character
| |
| CMP AL,0 ; Extended character ?
| |
| JNE Normal Char; No!
| |
| MOV AH,08H ; Function Call -- Console Input (no echo)
| |
| INT 21H ; Issue request to DOS
| |
| MOV ExtChar,AL ; Save extended character
| |
| Normal Char:
| |
|
| |
| Character LABEL WORD ; Complete character
| |
| Char DB ? ; Character buffer
| |
| ExtChar DB ? ; Character buffer
| |
|
| |
| COMMENTS
| |
|
| |
| The character is checked for Ctrl-Break. If Ctrl-Break is detected, an
| |
| interrupt 23H is executed.
| |
|
| |
| For function call 08H, extended ASCII codes require two function calls. The
| |
| first call returns 00H as an indicator that the next call will return an
| |
| extended code.
| |
|
| |
| 09H --
| |
| DISPLAY STRING
| |
|
| |
| PURPOSE
| |
|
| |
| Sends the characters in the string to the standard output device.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG String
| |
| MOV DS,AX ;Set DS:DX to string
| |
| MOV DX,OFFSET String
| |
| MOV AH,09H ;Function Call - Display String
| |
| INT 21H ;Issue request to DOS
| |
|
| |
|
| |
| String DB "This string ends at the first Dollar"
| |
| DB 0DH,0AH
| |
| DB "$"
| |
|
| |
| COMMENTS
| |
|
| |
| The character string in memory must be terminated by a $ (24H). Each
| |
| character in the string is output to the standard output device in the same
| |
| form as function call 02H.
| |
|
| |
| ASCII codes 0DH and 0AH represent carriage return and line feed,
| |
| respectively.
| |
|
| |
| 0AH --
| |
| BUFFERED KEYBOARD INPUT
| |
|
| |
| PURPOSE
| |
|
| |
| Reads characters from the standard input device and places them in the buffer
| |
| beginning at the third byte.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG Buffer
| |
| MOV DS,AX ;Set DS:DX to return Buffer
| |
| MOV DX,OFFSET Buffer
| |
| MOV AH,0AH ;Function Call-Buffered
| |
| ;Keyboard Input
| |
| INT 21H ;Issue request to DOS
| |
|
| |
|
| |
| Buffer DB 128 ; Max length of input
| |
| CurLen DB ? ; Number of characters input
| |
| ; (excludes Return (0DH))
| |
| CurText DB 128 DUP(?) ; Up to 128 characters allowed
| |
|
| |
| COMMENTS
| |
|
| |
| The first byte of the input buffer specifies the number of characters the
| |
| buffer can hold. This value cannot be 0. Reading the standard input device
| |
| and filling the buffer continues until Enter is read. If the buffer fills to
| |
| one less than the maximum number of characters it can hold, each additional
| |
| character read is ignored and causes the bell to ring, until Enter is read.
| |
| The second byte of the buffer is set to the number of characters received,
| |
| excluding the carriage return (0DH), which is always the last character.
| |
|
| |
| 0BH --
| |
| CHECK STANDARD INPUT STATUS
| |
|
| |
| PURPOSE
| |
|
| |
| Checks if there is a character available from the standard input device.
| |
|
| |
| EXAMPLE
| |
|
| |
| In LOOP:
| |
| MOV AH,0BH ; Function Call -- Check Input
| |
| INT 21H ; Issue request to DOS
| |
| CMP AL,-1 ; 0FFH indicates character available
| |
| JNE In LOOP:
| |
|
| |
| COMMENTS
| |
|
| |
| If a character is available from the STDIN device, AL is FFH. Otherwise, AL
| |
| is undefined. If a Ctrl-Break is detected, an interrupt 23H is executed.
| |
|
| |
| 0CH --
| |
| CLEAR KEYBOARD BUFFER AND INVOKE A KEYBOARD FUNCTION
| |
|
| |
| PURPOSE
| |
|
| |
| Clears the standard input device of any characters, then executes the
| |
| function call number in AL.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,0CH ; Function Call -- Clear keyboard &
| |
| ; Invoke function
| |
| MOV AL,Function ; Function Call to execute
| |
| ; (only 01H, 06H, 07H, 08H, and 0AH are allowed).
| |
| INT 21H ; Issue request to DOS
| |
| ; Output depends on Function Call selected
| |
|
| |
| 0DH --
| |
| DISK RESET
| |
|
| |
| PURPOSE
| |
|
| |
| Writes to the disk file buffers that have been modified. All buffers are
| |
| then made available for reuse.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,0DH ; Function Call -- Disk Reset
| |
| INT 21H ; Issue request to DOS
| |
| ; No return
| |
|
| |
| COMMENTS
| |
|
| |
| It is necessary to close or commit all open files to correctly update the
| |
| disk directory.
| |
|
| |
| 0EH --
| |
| SELECT DISK
| |
|
| |
| PURPOSE
| |
|
| |
| Selects the drive specified in DL (0=A, 1=B, etc.) (if valid) as the default
| |
| drive.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,0EH ; Function Call -- Select Disk
| |
| MOV DL,Drive ; Drive to select (0=A:, 1=B:, ...)
| |
| INT 21H ; Issue request to DOS
| |
| MOV LastDrive,AL : Save max drive number (1=A:, 2=B:, ...)
| |
| MOV AH,19H ; Function Call -- Get Current Disk
| |
| INT 21H ; Issue request to DOS
| |
| CMP AL,DL ; Selected drive = requested
| |
| JNE Error ; No, Error!
| |
|
| |
|
| |
| Drive DB ; New Drive to select
| |
| LastDrive DB ; Highest Valid Drive
| |
|
| |
| COMMENTS
| |
|
| |
| The total number of unique drive letters, including diskette and fixed disk
| |
| drives, that can be referenced is returned in AL. The value in AL is equal
| |
| to the value of LASTDRIVE in CONFIG.SYS or the total number of installed
| |
| devices, whichever is greater. For DOS 4.00 5 is the minimum value returned
| |
| in AL. If the system has only one diskette drive, it is counted as two to be
| |
| consistent with the philosophy of thinking of the system as having logical
| |
| drives A and B.
| |
|
| |
| 0FH --
| |
| OPEN FILE
| |
|
| |
| PURPOSE
| |
|
| |
| Searches the current directory for the named file and AL returns FFH if it is
| |
| not found. If the named file is found, AL returns 00H and the FCB is filled
| |
| as described below.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG FCB ;Address FCB Parameter Block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,0FH ;Function Call-FCB Open
| |
| INT 21H ;Issue request to DOS
| |
|
| |
|
| |
| FCB LABEL BYTE
| |
| Drive DB 0 ; Drive (0=Current, 1=A, 2=B, ...)
| |
| FName DB "FILENAME" ; File Name (blank padded)
| |
| Ext DB "EXT" ; File Extension (blank padded)
| |
| DB 25 DUP(0) ; Filled in by DOS 4.00
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the file is opened.
| |
|
| |
| AL is FFH if the file was not opened.
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition.
| |
|
| |
| If the drive code was 0 (default drive), it is changed to the actual drive
| |
| used (1=A, 2=B, and so on). This allows changing the default drive without
| |
| interfering with subsequent operations on this file. The current block field
| |
| (FCB bytes C-D) is set to 0. The size of the record to be worked with (FCB
| |
| bytes E-F) is set to the system default of 80H. The size of the file and the
| |
| date are set in the FCB from information obtained from the directory. You
| |
| can change the default value for the
| |
|
| |
| record size (FCB bytes E-F) or set the random record size and/or current
| |
| record field. Perform these actions after the open, but before any disk
| |
| operations.
| |
|
| |
| The file is opened in compatibility mode. For information on compatibility
| |
| mode, refer to function call 3DH.
| |
|
| |
| 10H --
| |
| CLOSE FILE
| |
|
| |
| PURPOSE
| |
|
| |
| Closes a file.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG FCB ; Address FCB Parameter Block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,10H ; Function Call-FCB Close
| |
| INT 21H ; Issue request to DOS
| |
| CMP AL,0 ; File Closed?
| |
| JNE Error ; No, Error!
| |
|
| |
|
| |
| FCB LABEL BYTE
| |
| ; Contents set by previous operations
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the file is closed.
| |
|
| |
| AL is FFH if the file was not closed.
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition.
| |
|
| |
| This function call must be executed on open files after file writes, and we
| |
| highly recommend that it be used on all files. If the file is not found in
| |
| its correct position in the current directory, it is assumed the disk was
| |
| changed and AL returns FFH. Otherwise, the directory is updated to reflect
| |
| the status in the FCB, the buffers for that file are flushed, and AL returns
| |
| 00H.
| |
|
| |
| 11H --
| |
| SEARCH FOR FIRST ENTRY
| |
|
| |
| PURPOSE
| |
|
| |
| Searches the current directory for the first matching filename.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG DTA ; Address Buffer for found file
| |
| MOV DS,AX ; information
| |
| MOV DX,OFFSET DTA
| |
| MOV AH,1AH ; Function Call-Set DTA address
| |
| INT 21H ; Issue request to DOS
| |
| MOV AX,SEG FCB ; Address FCB parameter block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,11H ; Function Call-FCB search first
| |
| INT 21H ; Issue request to DOS
| |
| CMP AL,0 ; File found?
| |
| JNE Error ; No, Error!
| |
|
| |
|
| |
| FCB LABEL BYTE
| |
| Fdrive DB 0 ; Drive (0=Current, 1=A, 2=B, ...)
| |
| Fname DB "FILENAME" ; File name (blank padded, may use ?)
| |
| Fext DB "EXT" ; File extension (blank padded, may use ?)
| |
| DB 25 DUP(0) ; Filled in by DOS
| |
|
| |
| DTA LABEL BYTE
| |
| Ddrive DB ? ; Drive
| |
| Dname DB "????????" ; File Name (blank padded)
| |
| Dext DB "???" ; File Extension (blank padded)
| |
| DB 25 DUP(0) ; Filled in by DOS 4.00
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the file is found.
| |
|
| |
| AL is FFH if the file was not found.
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition.
| |
|
| |
| The current disk directory is searched for the first matching filename. If
| |
| none are found, AL returns FFH. Global filename characters are allowed in
| |
| the filename and extension. If a matching filename is found, AL returns 00H
| |
| and the locations at the disk transfer address are set as follows:
| |
|
| |
| If the FCB provided for searching was an extended FCB, the first byte at
| |
| the disk transfer address is set to FFH followed by 5 bytes of 0, then
| |
| the attribute byte from the search FCB, then the drive number used (1=A,
| |
| 2=B, etc.), then the 32 bytes of the directory entry. Thus, the disk
| |
| transfer address contains a valid unopened extended FCB with the same
| |
| search attributes as the search FCB.
| |
|
| |
| If the FCB provided for searching was a standard FCB, then the first byte
| |
| is set to the drive number used (1=A, 2=B), and the next 32 bytes contain
| |
| the matching directory entry. Thus, the disk transfer address contains a
| |
| valid unopened normal FCB.
| |
|
| |
| NOTES:
| |
|
| |
| If an extended FCB is used, the following search pattern is used:
| |
|
| |
| 1. If the attribute is 0, only normal file entries are found. Entries for
| |
| volume label, sub-directories, hidden and system files, are not returned.
| |
|
| |
| 2. If the attribute field is set for hidden or system files, or directory
| |
| entries, it is an inclusive search. All normal file entries, plus all
| |
| entries matching the specified attributes, are returned. To look at all
| |
| directory entries except the volume label, the attribute byte may be set
| |
| to hidden + system + directory (all 3 bits on).
| |
|
| |
| 3. If the attribute field is set for the volume label, it is considered an
| |
| exclusive search, and only the volume label entry is returned.
| |
|
| |
| 12H --
| |
| SEARCH FOR NEXT ENTRY
| |
|
| |
| PURPOSE
| |
|
| |
| Searches the current directory for the next matching filename.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG DTA ; Address Buffer for found file
| |
| MOV DS,AX ; Information
| |
| MOV DX,OFFSET DTA
| |
| MOV AH,1AH ; Function Call-Set DTA address
| |
| INT 21H ; Issue request to DOS
| |
| MOV AX,SEG FCB ; Address FCB Parameter Block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,12H ; Function Call-FCB Search Next
| |
| INT 21H ; Issue request to DOS
| |
| CMP AL,0 ; File found?
| |
| JNE Error ; No, Error!
| |
|
| |
|
| |
| FCB LABEL BYTE
| |
| ; As set by FCB Search First
| |
|
| |
| DTA LABEL BYTE
| |
| Drive DB ? ; Drive
| |
| Fname DB "????????" ; File Name (blank padded)
| |
| Ext DB "???" ; File Extension (blank padded)
| |
| DB 25 DUP(0) ; Filled in by DOS 4.00
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the file is found.
| |
|
| |
| AL is FFH if the file was not found.
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition.
| |
|
| |
| After a matching filename has been found using function call 11H, function
| |
| 12H may be called to find the next match to an ambiguous request.
| |
|
| |
| The DTA contains information from the previous Search First or Search Next.
| |
| All of the FCB, except for the name/extension field, is used to keep
| |
| information necessary for continuing the search, so no disk operations may be
| |
| performed if this FCB is between a previous function 11H or 12H call and this
| |
| one.
| |
|
| |
| 13H --
| |
| DELETE FILE
| |
|
| |
| PURPOSE
| |
|
| |
| Deletes all current directory entries that match the specified filename. The
| |
| specified filename cannot be read-only.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG FCB ;Address FCB Parameter Block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,13H ;Function Call-FCB Delete File
| |
| INT 21H ;Issue request to DOS
| |
| CMP AL,0 ;File(s) Deleted?
| |
| JNE Error ;No, Error!
| |
|
| |
|
| |
| FCB LABEL BYTE
| |
| Drive DB 0 ; Drive
| |
| FName DB Filename ; File Name (blank padded, may
| |
| Ext DB Ext ; File Extension (blank padded, may
| |
| DB 25 DUP(0) ; Filled in by DOS
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the file is found.
| |
|
| |
| AL is FFH if the file was not found.
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition.
| |
|
| |
| All matching current directory entries are deleted. The global filename
| |
| character "?" is allowed in the filename or extension. If no directory
| |
| entries match, AL returns FFH; otherwise AL returns 00H.
| |
|
| |
| If the file is specified in read-only mode, the file is not deleted.
| |
|
| |
| NOTE: Close open files before deleting them.
| |
|
| |
| Network Access Rights: Requires Create access rights.
| |
|
| |
| 14H --
| |
| SEQUENTIAL READ
| |
|
| |
| PURPOSE
| |
|
| |
| Loads the record addressed by the current block (FCB bytes C-D) and the
| |
| current record (FCB byte 1F) at the disk transfer address (DTA), then the
| |
| record address is increased.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG DTA ;Address Data buffer
| |
| MOV DS,AX
| |
| MOV DX,OFFSET DTA
| |
| MOV AH,1AH ;Function call Set DTA Address
| |
| INT 21H ;Issue request to DOS
| |
| MOV AX,SEG FCB ;Address FCB Parameter Block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,14H ;Function Call-FCB Sequential Read
| |
| INT 21H ;Issue request to DOS
| |
| CMP AL,0 ;Data Read?
| |
| JNE Error ;No, Error!
| |
|
| |
|
| |
| FCB LABEL BYTE
| |
| ; Set by previous open
| |
| DTA LABEL BYTE
| |
| DB ?Dup(0) ;I/O buffer
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the read was successful.
| |
|
| |
| AL is 01H if the file was at End of File (EOF).
| |
|
| |
| AL is 02H if the read would have caused a wrap or overflow because the DTA
| |
| was too small (the read was not completed).
| |
|
| |
| AL is 03H if EOF (a partial record was read and filled out with 0's).
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition. The length of the record is determined by the FCB record size
| |
| field.
| |
|
| |
| Network Access Rights: Requires Read access rights.
| |
|
| |
| 15H --
| |
| SEQUENTIAL WRITE
| |
|
| |
| PURPOSE
| |
|
| |
| Writes the record addressed by the current block and record fields (size
| |
| determined by the FCB record size field) from the disk transfer address. If
| |
| records are less than the sector size, the record is buffered for an eventual
| |
| write when a sector's worth of data is accumulated. Then the record address
| |
| is increased.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG DTA ;Address Data buffer
| |
| MOV DS,AX
| |
| MOV DX,OFFSET DTA
| |
| MOV AH,1AH ;Function Set DTA Address
| |
| INT 21H ;Issue request to DOS
| |
| MOV AX,SEG FCB ;Address FCB Parameter Block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,15H ;Function Call-FCB Sequential Write
| |
| INT 21H ;Issue request to DOS
| |
| CMP AL,0 ;Data Written?
| |
| JNE Error ;No, Error!
| |
|
| |
| FCB LABEL BYTE
| |
| ; Set by previous open
| |
| DTA LABEL BYTE
| |
| DB ?Dup(0) ;I/O buffer
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the write was successful.
| |
|
| |
| AL is 01H if the disk or diskette is full (write cancelled).
| |
|
| |
| AL is 02H if the write would have caused a wrap or overflow because the DTA
| |
| was too small (write cancelled).
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition. If the file is specified in read-only mode, the sequential write
| |
| is not performed and 01H is returned in AL.
| |
|
| |
| Network Access Rights: Requires Write access rights.
| |
|
| |
| 16H --
| |
| CREATE FILE
| |
|
| |
| PURPOSE
| |
|
| |
| Creates a new file.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG FCB ;Address FCB parameter block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,16H ;Function Call-FCB create file
| |
| INT 21H ;Issue request to DOS
| |
| CMP AL,0 ;File created and opened?
| |
| JNE Error ;No, Error!
| |
|
| |
|
| |
| FCB LABEL BYTE
| |
| Fdrive DB 0 ; Drive (0=Current, 1=A, 2=B, ...)
| |
| Fname DB "FILENAME" ; File name (blank padded)
| |
| Fext DB "EXT" ; File extension (blank padded)
| |
| DB 25 DUP(0) ; Filled in by DOS
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the file is created and opened.
| |
|
| |
| AL is FFH if the file was not created (normally a full directory or disk
| |
| full).
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition.
| |
|
| |
| If a matching entry is found it is reused. If no match is found, the
| |
| directory is searched for an empty entry. If a match is found, the entry is
| |
| initialized to a 0-length file, the file is opened (see function call 0FH),
| |
| and AL returns 00H.
| |
|
| |
| The file may be marked hidden during its creation by using an extended FCB
| |
| containing the appropriate attribute byte.
| |
|
| |
| Network Access Rights: Requires Create access rights.
| |
|
| |
| 17H --
| |
| RENAME FILE
| |
|
| |
| PURPOSE
| |
|
| |
| Changes every matching occurrence of the first filename in the current
| |
| directory of the specified drive to the second, with the restriction that two
| |
| files cannot have the same name and extension.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG FCB ;Address FCB Parameter Block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,17H ;Function Call-FCB Rename File
| |
| INT 21H ;Issue request to DOS
| |
| CMP AL,0 ;File(s) Renamed?
| |
| JNE Error ;No, Error!
| |
|
| |
|
| |
| FCB LABEL BYTE
| |
| Fdrive DB 0 ; Drive (0=Current, 1=A, 2=B, ...)
| |
| Fname DB "FILENAME" ; File Name (blank padded, may use ?
| |
| Fext DB "EXT" ; File Extension (blank padded, may use ?
| |
| DB 5 DUP(0) ; Reserved
| |
| NewName DB "FILENAME" ; New File Name (blank padded, may use ?
| |
| NewExt DB "EXT" ; New File Extension (blank padded, may use ?
| |
| DB 7 DUP(0) ; Reserved
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the file or files were renamed.
| |
|
| |
| AL is FFH if a file in the current directory did not match or the new name
| |
| already exists.
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition.
| |
|
| |
| The modified FCB has a drive code and filename in the usual position, and a
| |
| second filename on the sixth byte after the first (DS:DX+11H) in what is
| |
| normally a reserved area.
| |
|
| |
| If "?"s appear in the second name, the corresponding positions in the
| |
| original name are unchanged.
| |
|
| |
| If the file is specified in read-only mode, the file is not renamed.
| |
|
| |
| Network Access Rights: Requires Create access rights.
| |
|
| |
| 19H --
| |
| CURRENT DISK
| |
|
| |
| PURPOSE
| |
|
| |
| Determines the current default drive.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,19H ; Function Call -- Get Current Disk
| |
| INT 21H ; Issue request to DOS
| |
| MOV Disk,AL ; Save Current Disk
| |
|
| |
| Disk DB ? ; Current Disk code (0=A:, 1=B:, ...)
| |
|
| |
| COMMENTS
| |
|
| |
| AL returns with the code of the current default drive (0=A, 1=B, and
| |
| others.).
| |
|
| |
| 1AH --
| |
| SET DISK TRANSFER ADDRESS
| |
|
| |
| PURPOSE
| |
|
| |
| Sets the disk transfer address to DS:DX.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG DTA ;Address Buffer
| |
| MOV DS,AX
| |
| MOV DX,OFFSET DTA
| |
| MOV AH,1AH ;Function Call-Set DTA address
| |
| INT 21H ;Issue request to DOS
| |
|
| |
| DTA LABEL BYTE ; Data Buffer
| |
|
| |
| COMMENTS
| |
|
| |
| The area defined by this call is from the address in DS:DX to the end of the
| |
| segment in DS. DOS 4.00 does not allow disk transfers to wrap around within
| |
| the segment, or overflow into the next segment. If you do not set the DTA,
| |
| the default DTA is offset 80H in the program segment prefix. To get the DTA,
| |
| issue function call 2FH.
| |
|
| |
| 1BH --
| |
| ALLOCATION TABLE INFORMATION
| |
|
| |
| PURPOSE
| |
|
| |
| Returns information about the allocation table for the default drive.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,1BH ; Function Call -- Allocation Table
| |
| ; Information
| |
| INT 21H ; Issue request to DOS
| |
| MOV NumAllocUnits,DX ; Save Number of Allocation Units
| |
| MOV NumSectsAllocUnit,AL ; Save Number of Sectors/Allocation Unit
| |
| MOV SectSize,CX ; Save of Sector Size
| |
| MOV WORD PTR MediaType@+0,BX; Save Pointer to Media Type Byte
| |
| MOV WORD PTR MediaType@+2,DS
| |
|
| |
|
| |
| NumAllocUnits DW ? ; Number of Allocation Units on Current
| |
| NumSectsAllocUnit DB ? ; Number Sectors in an Allocation Unit
| |
| SectSize DW ? ; Sector Size
| |
| MediaType@ DD ? ; Pointer to Media Type byte
| |
|
| |
| COMMENTS
| |
|
| |
| Refer to function call 36H (Get Disk Free Space).
| |
|
| |
| 1CH --
| |
| ALLOCATION TABLE INFORMATION FOR SPECIFIC DEVICE
| |
|
| |
| PURPOSE
| |
|
| |
| Returns allocation table information for a specific device.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,1CH ; Function Call --
| |
| ; Allocation Table Information
| |
| MOV DL,Drive ; Drive requested (0=current,
| |
| ; 1=A:, ...)
| |
| INT 21H ; Issue request to DOS
| |
| MOV NumAllocUnits,DX ; Save Number of Allocation Units
| |
| MOV NumSectsAllocUnit,AL ; Save Number of Sectors/Allocation Unit
| |
| MOV SectSize,CX ; Save of Sector Size
| |
| MOV WORD PTR MediaType@+0,BX ; Save Pointer to Media Type Byte
| |
| MOV WORD PTR MediaType@+2,DS
| |
|
| |
| Drive DB ; drive number to get info for
| |
| NumAllocUnits DW ? ; Number of Allocation Units
| |
| ; on specified drive
| |
| NumSectsAllocUnit DB ? ; Number Sectors in an
| |
| ; Allocation Unit
| |
| SectSize DW ? ; Sector Size
| |
| MediaType@ DD ? ; Pointer to Media Type byte
| |
|
| |
| COMMENTS
| |
|
| |
| This call is the same as call 1BH, except that on entry DL contains the
| |
| number of the drive that contains the needed information (0 = default, 1 = A,
| |
| and so forth.). For more information on DOS 4.00 disk allocation, refer to
| |
| "The Disk Directory" on page 2-3. Also, refer to function call 36H (Get Disk
| |
| Free Space).
| |
|
| |
| 21H --
| |
| RANDOM READ
| |
|
| |
| PURPOSE
| |
|
| |
| Reads the record addressed by the current block and current record fields
| |
| into memory at the current disk transfer address.
| |
|
| |
| EXAMPLE
| |
|
| |
| ;Set up FCB
| |
| MOV AX,SEG DTA ;Address Data buffer
| |
| MOV DS,AX
| |
| MOV DX,OFFSET DTA
| |
| MOV AH,1AH ;Function Set DTA Address
| |
| INT 21H ;Issue request to DOS
| |
| MOV AX,SEG FCB ;Address FCB Parameter Block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,21H ;Function Call-FCB Random Read
| |
| INT 21H ;Issue request to DOS
| |
| CMP AL,0 ;Data Read?
| |
| JNE Error ;No, Error!
| |
|
| |
|
| |
| FCB LABEL BYTE
| |
| ; Set by previous open
| |
| ; DTA label byte
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the read was successful.
| |
|
| |
| AL is 01H if the file was at End of File (EOF) (no data read).
| |
|
| |
| AL is 02H if the read would have caused a wrap or overflow because the DTA
| |
| was too small (the read was not completed).
| |
|
| |
| AL is 03H if EOF (a partial record was read and filled out with 0's).
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition.
| |
|
| |
| The current block and current record fields are set to agree with the random
| |
| record field. The record addressed by these fields is read into memory at
| |
| the current disk transfer address. For information on record size see
| |
| Chapter 4, "Accessing Files Using File Control Blocks" on page 4-1.
| |
|
| |
| NOTE: Function 24H must be called before using this function.
| |
|
| |
| Network Access Rights: Requires Read access rights.
| |
|
| |
| 22H --
| |
| RANDOM WRITE
| |
|
| |
| PURPOSE
| |
|
| |
| Writes the record addressed by the current block and current record fields
| |
| from the current disk transfer address.
| |
|
| |
| EXAMPLE
| |
|
| |
| ;Set up FCB
| |
|
| |
| MOV AX,SEG FCB ;Address FCB parameter block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,24H ;Function Call--FCB Set
| |
| ;Relative record field
| |
| INT 21H ;Issue request to DOS
| |
| MOV AX,SEG DTA ;Address data buffer
| |
| MOV DS,AX
| |
| MOV DX,OFFSET DTA
| |
| MOV AH,1AH ;Function Set DTA address
| |
| INT 21H ;Issue request to DOS
| |
| MOV AX,SEG FCB ;Address FCB parameter block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,22H ;Function Call-FCB random writers
| |
| INT 21H ;Issue request to DOS
| |
| CMP AL,0 ;Data written?
| |
| JNE Error ;No, error!
| |
|
| |
|
| |
| FCB LABEL BYTE
| |
| ; Set by previous open
| |
| DTA LABEL BYTE
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the write was successful.
| |
|
| |
| AL is 01H if the write or diskette is full (write cancelled).
| |
|
| |
| AL is 02H if the read would have caused a wrap or overflow because the DTA
| |
| was too small (write cancelled).
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition.
| |
|
| |
| The current block and current record fields are set to agree with the random
| |
| record field. Then the record addressed by these fields is written (or in
| |
| the case of records not the same as sector sizes -- buffered) from the disk
| |
| transfer address.
| |
|
| |
| If the file is specified in read-only mode, the random write is not
| |
| performed.
| |
|
| |
| Network Access Rights: Requires Write access rights.
| |
|
| |
| 23H --
| |
| FILE SIZE
| |
|
| |
| PURPOSE
| |
|
| |
| Searches the current directory for an entry that matches the specified file
| |
| and sets the FCBs random record field to the number of records in the file.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG FCB ; Address FCB parameter block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,23H ; Function Call-FCB file size
| |
| INT 21H ; Issue request to DOS
| |
| CMP AL,0 ; File found?
| |
| JNE Error ; No, error!
| |
|
| |
|
| |
| FCB LABEL BYTE
| |
| Drive DB 0 ; Drive (0=Current, 1=A, 2=B, ...)
| |
| Name DB "FILENAME" ; File name (blank padded)
| |
| Ext DB "EXT" ; File extension (blank padded)
| |
| DB 25 DUP(0) ; Filled in by DOS
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the file exists.
| |
|
| |
| AL is FFH if the file was not created (normally a full directory or disk
| |
| full).
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition.
| |
|
| |
| The directory is searched for the matching entry. If a matching entry is
| |
| found, the random record field is set to the number of records in the file
| |
| (in terms of the record size field rounded up). If no matching entry is
| |
| found, AL returns FFH.
| |
|
| |
| NOTE: If you do not set the FCB record size field before using this
| |
| function, incorrect information is returned.
| |
|
| |
| 24H --
| |
| SET RELATIVE RECORD FIELD
| |
|
| |
| PURPOSE
| |
|
| |
| Sets the random record field to the same file address as the current block
| |
| and record fields.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG FCB ;Address FCB parameter block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,24H ;Function Call--FCB set
| |
| ;Relative record field
| |
| INT 21H ;Issue request to DOS
| |
|
| |
|
| |
| FCB LABEL BYTE
| |
| ; Set by previous open
| |
|
| |
| COMMENTS
| |
|
| |
| You must call this function before you perform random reads and writes, and
| |
| random block reads and writes.
| |
|
| |
| 25H --
| |
| SET INTERRUPT VECTOR
| |
|
| |
| PURPOSE
| |
|
| |
| Sets the interrupt vector table for the interrupt number.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG Handler ;Address new handler
| |
| MOV DS,AX
| |
| MOV DX,OFFSET Handler
| |
| MOV AH,25H ;Function Call - Set Interrupt
| |
| ;Vector
| |
| MOV AL,Vector
| |
| INT 21H ;Issue request to DOS
| |
|
| |
|
| |
| Vector DB ? ;Number of vector to be replaced
| |
| Handler: ;Code to process interrupt
| |
|
| |
| COMMENTS
| |
|
| |
| The interrupt vector table for the interrupt number specified in AL is set to
| |
| address contained in DS:DX. Use function call 35H (Get Interrupt Vector) to
| |
| obtain the contents of the interrupt vector.
| |
|
| |
| 26H --
| |
| CREATE NEW PROGRAM SEGMENT
| |
|
| |
| PURPOSE
| |
|
| |
| Creates a new program segment.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,26H ; Function Call -- Create Program
| |
| ; Segment
| |
| MOV DX,SEG PSP ; Segment address to create new PSP
| |
| INT 21H ; Issue request to DOS
| |
|
| |
|
| |
| PSP LABEL BYTE ; Area to fill in
| |
| DB 100H DUP(0)
| |
|
| |
| COMMENTS
| |
|
| |
| The entire 100H area at location 0 in the current program segment is copied
| |
| into location 0 in the new program segment. The memory size information at
| |
| location 6 in the new segment is updated and the current termination,
| |
| Ctrl-Break exit and critical error addresses from interrupt vector table
| |
| entries for interrupts 22H, 23H, and 24H are saved in the new program segment
| |
| starting at 0AH. They are restored from this area when the program ends.
| |
|
| |
| NOTE: The EXEC function call 4BH provides a more complete service.
| |
| Therefore, you should use the EXEC 4BH and avoid using this call.
| |
|
| |
| 27H --
| |
| RANDOM BLOCK READ
| |
|
| |
| PURPOSE
| |
|
| |
| Reads the specified number of records (in terms of the record size field)
| |
| from the file address specified by the random record field into the disk
| |
| transfer address.
| |
|
| |
| EXAMPLE
| |
|
| |
| ;Set up disk transfer address
| |
|
| |
| MOV AX,SEG DTA ;Address data buffer
| |
| MOV DS,AX
| |
| MOV DX,OFFSET DTA
| |
| MOV AH,1AH ;Function set DTA address
| |
| INT 21H ;Issue request to DOS
| |
|
| |
| MOV AX,SEG FCB ;Address FCB parameter block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,24H ;Function Call -- FCB Set
| |
| ;Relative Record Field
| |
| INT 21H ;Issue request to DOS
| |
| MOV AX,SEG FCB ;Address FCB parameter block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV CX,Records to read ;number of records to read
| |
| MOV AH,27H ;Function Call - FCB random block read
| |
| INT 21H ;Issue request to DOS
| |
| CMP AL,0 ;Data read?
| |
| JNE Error ;No, error!
| |
|
| |
|
| |
| FCB LABEL BYTE
| |
| ; Set by previous open
| |
| DTA LABEL BYTE
| |
| DB ?Dup(0) ;I/O buffer
| |
| Records to read DW ?
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the read was successful.
| |
|
| |
| AL is 01H if the file was at End of File (EOF) (no data read).
| |
|
| |
| AL is 02H if the read would have caused a wrap or overflow because the DTA
| |
| was too small (the read was not completed.).
| |
|
| |
| AL is 03H if EOF (a partial record was read and filled out with zeros).
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition.
| |
|
| |
| The random record field and the current block/record fields are set to
| |
| address the next record (the first record not read).
| |
|
| |
| NOTE: Function 24H must be called before using this function.
| |
|
| |
| Network Access Rights: Requires Read access rights.
| |
|
| |
| 28H --
| |
| RANDOM BLOCK WRITE
| |
|
| |
| PURPOSE
| |
|
| |
| Writes the specified number of records from the disk transfer address into
| |
| the file address specified by the random record field.
| |
|
| |
| EXAMPLE
| |
|
| |
| ;Set up disk transfer address
| |
| MOV AX,SEG DTA ;Address data buffer
| |
| MOV DS,AX
| |
| MOV DX,OFFSET DTA
| |
| MOV AH,1AH ;Function set DTA address
| |
| INT 21H ;Issue request to DOS
| |
|
| |
| MOV AX,SEG FCB ;Address FCB parameter block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV AH,24H ;Function Call--FCB set
| |
| ;Relative record field
| |
| INT 21H ;Issue request to DOS
| |
|
| |
| MOV AX,SEG FCB ;Address FCB parameter block
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FCB
| |
| MOV CX,Records to write ;Number of records to write
| |
| MOV AH,28H ;Function Call - FCB Random Block write
| |
| INT 21H ;Issue request to DOS
| |
| CMP AL,0 ;Data written?
| |
| JNE Error ;No, error!
| |
|
| |
|
| |
| DTA LABEL BYTE
| |
|
| |
| DB ?DUP(0) ; I/O Buffer
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the write was successful.
| |
|
| |
| AL is 01H if the disk or diskette is full (write cancelled).
| |
|
| |
| AL is 02H if the write would have caused a wrap or overflow because the DTA
| |
| was too small (write cancelled).
| |
|
| |
| Use Function Call 59H (Get Extended Error) to determine the actual error
| |
| condition.
| |
|
| |
| If there is insufficient space on the disk, AL returns 01H and no records are
| |
| written. If CX is 0 upon entry, no records are written, but the file is set
| |
| to the length specified by the random record field, whether longer or shorter
| |
| than the current file size. (Allocation units are released or allocated as
| |
| appropriate.)
| |
|
| |
| NOTE: Function call 24H must be called before using this function.
| |
|
| |
| Network Access Rights: Requires Write access rights.
| |
|
| |
| 29H --
| |
| PARSE FILENAME
| |
|
| |
| PURPOSE
| |
|
| |
| Parses the specified filename.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG CmdBuf
| |
| MOV DS,AX ;Address command string
| |
| MOV SI,OFFSET CmdBuf
| |
| MOV AX,SEG FCB
| |
| MOV ES,AX ;Address FCB Parameter Block
| |
| MOV DI,OFFSET FCB
| |
| MOV AH,29H ;Function Call - FCB Parse Filename
| |
| MOV AL,OPTIONS ;Set desired action
| |
| INT 21H ;Issue request to DOS
| |
|
| |
| CMP AL,-1 ;Drive valid?
| |
| JE Error ;No, Error!
| |
|
| |
| CmdBuf LABEL BYTE
| |
| DB " a:file.ext ",0DH
| |
|
| |
| FCB LABEL BYTE
| |
| ; Created in a pre-open state based on input found.
| |
| Options DB ? ;parsing options
| |
|
| |
| COMMENTS
| |
|
| |
| The contents of AL are used to determine the action to take, as shown below:
| |
|
| |
| <must = 0>
| |
| bit: 7 6 5 4 3 2 1 0
| |
|
| |
| If bit 0 = 1, leading separators are scanned off the command line at DS:SI.
| |
| Otherwise, no scan-off of leading separators takes place.
| |
|
| |
| If bit 1 = 1, the drive ID byte in the FCB will be set (changed) only if a
| |
| drive was specified in the command line being parsed.
| |
|
| |
| If bit 2 = 1, the filename in the FCB will be changed only if the command
| |
| line contains a filename.
| |
|
| |
| If bit 3 = 1, the filename extension in the FCB will be changed only if the
| |
| command line contains a filename extension.
| |
|
| |
| Filename separators include the following characters:
| |
|
| |
| : . : , = + along with TAB and SPACE. Filename terminators include all of
| |
| these characters plus ,<, >, |, /, ', [, ], and any control characters.
| |
|
| |
| Output:
| |
|
| |
| AL is 00H if no global characters (? or *) were found in the Command String.
| |
|
| |
| AL is 01H if global characters (? or *) were found in the Command String.
| |
|
| |
| AL is FFH if the drive specified is invalid.
| |
|
| |
| The command line is parsed for a filename of the form d:filename.ext, and if
| |
| found, a corresponding unopened FCB is created at ES:DI. If no drive
| |
| specifier is present, it is assumed to be all blanks. If the character *
| |
| appears in the filename or extension, it and all remaining characters in the
| |
| name or extension are set to ?.
| |
|
| |
| DS:SI returns pointing to the first character after the filename and ES:DI
| |
| points to the first byte of the formatted FCB. If no valid filename is
| |
| present, ES:DI+1 contains a blank.
| |
|
| |
| 2AH --
| |
| GET DATE
| |
|
| |
| PURPOSE
| |
|
| |
| Returns the day of the week, the year, month and date.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,2AH ; Function Call -- Get Date
| |
| INT 21H ; Issue request to DOS
| |
| MOV DayofWeek,AL ; Save Day of the Week
| |
| MOV Year,CX ; Save Year
| |
| MOV Month,DH ; Save Month
| |
| MOV Day,DL ; Save Day
| |
|
| |
|
| |
| DayofWeek DB ? ; 0=Sunday, ... 6=Saturday
| |
| Year DW ? ; 1980 to 2099
| |
| Month DB ? ; 1 to 12
| |
| Day DB ? ; 1 to 31
| |
|
| |
| COMMENTS
| |
|
| |
| If the time-of-day clock rolls over to the next day, the date is adjusted
| |
| accordingly, taking into account the number of days in each month and leap
| |
| years.
| |
|
| |
| 2BH --
| |
| SET DATE
| |
|
| |
| PURPOSE
| |
|
| |
| Sets the date (also sets CMOS clock, if present).
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,2BH ; Function Call -- Set Date
| |
| MOV CX,Year ; Set Year
| |
| MOV DH,Month ; Set Month
| |
| MOV DL,Day ; Set Day
| |
| INT 21H ; Issue request to DOS
| |
| CMP AL,0 ; Valid Date?
| |
| JNE Error ; No!
| |
|
| |
| Year DW ? ; 1980 to 2099
| |
| Month DB ? ; 1 to 12
| |
| Day DB ? ; 1 to 31
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the date is valid and the operation is successful.
| |
|
| |
| AL is FFH if the date is not valid.
| |
|
| |
| On entry, CX:DX must have a valid date in the same format as returned by
| |
| function call 2AH.
| |
|
| |
| On return, AL returns 00H if the date is valid and the set operation is
| |
| successful. AL returns FFH if the date is not valid.
| |
|
| |
| 2CH --
| |
| GET TIME
| |
|
| |
| PURPOSE
| |
|
| |
| Returns the time; hours, minutes, seconds and hundredths of seconds.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,2CH ; Function Call --
| |
| ; Get Time
| |
| INT 21H ; Issue request to DOS
| |
| MOV Hour,CH ; Save Hour
| |
| MOV Minute,CL ; Save Minute
| |
| MOV Second,DH ; Save Second
| |
| MOV Hundredth,DL ; Save Partial Second
| |
|
| |
|
| |
| Hour DB ? ; 0 to 23
| |
| Minute DB ? ; 0 to 59
| |
| Second DB ? ; 0 to 59
| |
| Hundredth DB ? ; 0 to 99
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, AH contains 2CH. On return, CX:DX contains the time-of-day. Time
| |
| is actually represented as four 8-bit binary quantities as follows:
| |
|
| |
| CH Hours (0-23)
| |
| CL Minutes (0-59)
| |
| DH Seconds (0-59)
| |
| DL 1/100 seconds (0-99).
| |
|
| |
| This format is readily converted to a printable form yet can also be used for
| |
| calculations, such as subtracting one time value from another.
| |
|
| |
| 2DH --
| |
| SET TIME
| |
|
| |
| PURPOSE
| |
|
| |
| Sets the time (also sets the CMOS clock, if present).
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,2DH ; Function Call -- Set Time
| |
| MOV CH,Hour ; Sst Hour
| |
| MOV CL,Minute ; Set Minute
| |
| MOV DH,Second ; Set Second
| |
| MOV DL,Hundredth ; Set Partial Second
| |
| INT 21H ; Issue request to DOS
| |
| CMP AL,0 ; Valid Time?
| |
| JNE Error ; No!
| |
|
| |
|
| |
| Hour DB ? ; 0 to 23
| |
| Minute DB ? ; 0 to 59
| |
| Second DB ? ; 0 to 59
| |
| Hundredth DB ? ; 0 to 99
| |
|
| |
| COMMENTS
| |
|
| |
| AL is 00H if the time is valid.
| |
|
| |
| AL is FFH if the time is not valid.
| |
|
| |
| On entry, CX:DX has time in the same format as returned by function 2CH. On
| |
| return, if any component of the time is not valid, the set operation is
| |
| cancelled and AL returns FFH. If the time is valid, AL returns 00H.
| |
|
| |
| If your system has a CMOS realtime clock, it will be set.
| |
|
| |
| 2EH --
| |
| SET/RESET VERIFY SWITCH
| |
|
| |
| PURPOSE
| |
|
| |
| Sets the verify switch.
| |
|
| |
| EXAMPLE
| |
|
| |
| ; To set VERIFY=OFF
| |
|
| |
| MOV AH,2EH ; Function Call -- Set
| |
| ; VERIFY
| |
| MOV AL,0 ; Set OFF
| |
| INT 21H ; Issue request to DOS
| |
|
| |
| ; To set VERIFY=ON
| |
|
| |
| MOV AH,2EH ; Function Call -- Set
| |
| ; VERIFY
| |
| MOV AL,1 ; Set ON
| |
| INT 21H ; Issue request to DOS
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, AL must contain 01H to turn verify on, or 00H to turn verify off.
| |
| When verify is on, DOS 4.00 performs a verify operation each time it performs
| |
| a disk write to assure proper data recording. Although disk recording errors
| |
| are very rare, this function has been provided for applications in which you
| |
| may wish to verify the proper recording of critical data. You can obtain the
| |
| current setting of the verify switch through function call 54H.
| |
|
| |
| NOTE: Verification is not supported on data written to a network disk.
| |
|
| |
| 2FH --
| |
| GET DISK TRANSFER ADDRESS (DTA)
| |
|
| |
| PURPOSE
| |
|
| |
| Returns the current disk transfer address.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,2FH ; Function Call -- Get
| |
| ; DTA Address
| |
| INT 21H ; Issue request to DOS
| |
| MOV WORD PTR DTA@+0,BX ; Save Address
| |
| MOV WORD PTR DTA@+2,ES
| |
|
| |
|
| |
| DTA@ DD ? ; DTA Buffer
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, AH contains 2FH. On return, ES:BX contains the current Disk
| |
| Transfer Address. You can set the DTA using function call 1AH.
| |
|
| |
| 30H --
| |
| GET DOS VERSION NUMBER
| |
|
| |
| PURPOSE
| |
|
| |
| Returns the DOS version number.
| |
|
| |
| EXAMPLE
| |
|
| |
| PUSH CX ; CX and BX destroyed in call
| |
| PUSH BX
| |
| MOV AH,30H ; Function Call -- Get DOS 4.00
| |
| ; Version
| |
| INT 21H ; Issue request to DOS
| |
| MOV MajorVersion,AL ; Save Version
| |
| MOV MinorVersion,AH
| |
| POP BX
| |
| POP CX
| |
|
| |
| MajorVersion DB ? ; X of X.YY
| |
| MinorVersion DB ? ; YY of X.YY
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, AH contains 30H. On return, BX and CX are set to 0. AL contains
| |
| the major version number. AH contains the minor version number.
| |
|
| |
| If AL returns a major version number of 0, you can assume that the DOS
| |
| version is pre-DOS 2.00.
| |
|
| |
| 31H --
| |
| TERMINATE PROCESS AND REMAIN RESIDENT
| |
|
| |
| PURPOSE
| |
|
| |
| Terminates the current process and attempts to set the initial allocation
| |
| block to the memory size in paragraphs.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,31H ; Function Call -- Terminate
| |
| ; and Keep Process
| |
| MOV AL,RetCode ; Set value of ERRORLEVEL
| |
| MOV DX,MySize ; Set my program and data size
| |
| INT 21H ; Issue request to DOS
| |
| INT 20H ; Be safe if on DOS 4.00 Version 1.X
| |
|
| |
|
| |
| RetCode DB ? ; Value to return to my EXEC'er
| |
| MySize DW ? ; Size of my code and data
| |
| ; (in paragraphs)
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, AL contains a binary return code. DX contains the memory size
| |
| value in paragraphs. This function call does not free up any other
| |
| allocation blocks belonging to that process. Files opened by the process are
| |
| not closed when the call is executed. The return code passed in AL is
| |
| retrievable by the parent through Wait (function call 4DH) and can be tested
| |
| through the ERRORLEVEL batch subcommands.
| |
|
| |
| Memory is used efficiently if the block containing a copy of the environment
| |
| is deallocated before terminating. This can be done by loading ES with the
| |
| segment contained in 2C of the PSP, and issuing function call 49H (Free
| |
| Allocated Memory). The five standard handles, 0000 through 0004, should be
| |
| closed before exiting.
| |
|
| |
| 33H --
| |
| GET/SET SYSTEM VALUE
| |
|
| |
| PURPOSE
| |
|
| |
| Set or get the state of System Values such as BREAK (Ctrl-Break checking).
| |
|
| |
| EXAMPLE
| |
|
| |
| ; To check BREAK state
| |
|
| |
| MOV AH,33H ; Function Call -- Get/Set
| |
| ; System value
| |
| MOV AL,0 ; Do Get BREAK
| |
| INT 21H ; Issue request to DOS
| |
| MOV BREAK,DL ; Save state
| |
|
| |
| ; To set BREAK=OFF
| |
|
| |
| MOV AH,33H ; Function Call -- Get/Set
| |
| ; System value
| |
| MOV AL,1 ; Do Set BREAK
| |
| MOV DL,0 ; Set OFF
| |
| INT 21H ; Issue request to DOS
| |
|
| |
| ; To set BREAK=ON
| |
|
| |
| MOV AH,33H ; Function Call -- Get/Set
| |
| ; System Value
| |
| MOV AL,1 ; Do Set BREAK
| |
| MOV DL,1 ; Set ON
| |
| INT 21H ; Issue request to DOS
| |
|
| |
| ; To get the Boot Drive
| |
|
| |
| MOV AH,33H ; Function Call -- Get/Set
| |
| ; System Value
| |
| MOV AL,5 ; Do Get Boot Drive
| |
| INT 21H ; Issue request to DOS
| |
| MOV Drive,DL ; Save boot drive
| |
|
| |
|
| |
| BREAK DB ? ; Current BREAK state (0=OFF, 1=ON)
| |
| Drive DB ? ; DOS 4.00 boot drive
| |
|
| |
| COMMENTS
| |
|
| |
| For BREAK:
| |
|
| |
| AL contains 00H to request the current state of Ctrl-Break checking. On
| |
| return DL contains the current state (00H = OFF, 01H = ON).
| |
|
| |
| AL contains 01H to set the state. DL contains the new state (00H = OFF, 01H
| |
| = ON).
| |
|
| |
| For boot drive:
| |
|
| |
| AL contains 05H to request the boot drive. On return DL contains the drive
| |
| (A:=1, C:=3, ...).
| |
|
| |
| 35H --
| |
| GET INTERRUPT VECTOR
| |
|
| |
| PURPOSE
| |
|
| |
| To obtain the address in an interrupt vector.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,35H ; Function Call --
| |
| ; Set Interrupt Vector
| |
| MOV AL,Vector ; Vector to get (0 to 255)
| |
| INT 21H ; Issue request to DOS
| |
| MOV WORD PTR OldVect+0,BX
| |
| MOV WORD PTR OldVect+2,ES
| |
|
| |
|
| |
| OldVect DD ? ; Previous vector contents
| |
| Vector DB ? ; Vector number to get
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, AH contains 35H. AL contains a hexadecimal interrupt number. On
| |
| return, ES:BX contains the CS:IP interrupt vector for the specified
| |
| interrupt. Use function call 25H (Set Interrupt Vector) to set the interrupt
| |
| vectors.
| |
|
| |
| 36H --
| |
| GET DISK FREE SPACE
| |
|
| |
| PURPOSE
| |
|
| |
| Returns the disk free space (available clusters, clusters/drive,
| |
| bytes/sector).
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,36H ; Function Call --
| |
| ; Get disk free space
| |
| MOV DL,Drive ; Drive to query
| |
| ; (0=current, 1=A:,
| |
| ; 2=B:, ...)
| |
| INT 21H ; Issue request to DOS
| |
| CMP AX,-1 ; Error?
| |
| JE Error ; Yes
| |
| MOV SectAU,AX ; Save allocation unit
| |
| ; Size
| |
| MOV AvailAU,BX ; Save free allocation
| |
| ; Units
| |
| MOV SectSize,CX ; Save sector size
| |
| MOV TotalAU,DX ; Save disk size
| |
|
| |
| MOV AX,SectSize ; Calculate allocation
| |
| ; Unit size
| |
| MUL SectAU
| |
| MOV CX,AX ; CX = bytes/AU
| |
| MOV AX,TotalAU ; Calculate total space
| |
| MUL CX
| |
| MOV WORD PTR TotalBytes+0,AX ; Save it
| |
| MOV WORD PTR TotalBytes+2,DX
| |
| MOV AX,AvailAU ; Calculate free space
| |
| MUL CX
| |
| MOV WORD PTR FreeBytes+0,AX ; Save it
| |
| MOV WORD PTR FreeBytes+2,DX
| |
|
| |
|
| |
| SectAU DW ? ; Sectors in an
| |
| ; Allocation unit
| |
| AvailAU DW ? ; Free allocation units
| |
| SectSize DW ? ; Bytes in a sector
| |
| TotalAU DW ? ; Number of allocation
| |
| ; Units on DL disk
| |
| TotalBytes DD ? ; Disk size in bytes
| |
| FreeBytes DD ? ; Free space in bytes
| |
| Drive DD ? ; Drive number to get info for
| |
|
| |
| COMMENTS
| |
|
| |
| If the drive number in DL was valid, BX contains the number of available
| |
| allocation units, DX contains the total number of allocation units on the
| |
| drive, CX contains the number of bytes per sector, and AX contains the number
| |
| of sectors for each allocation unit.
| |
|
| |
| 38H --
| |
| GET OR SET COUNTRY DEPENDENT INFORMATION
| |
|
| |
| PURPOSE
| |
|
| |
| Sets the Active Country or returns country dependent information.
| |
|
| |
| EXAMPLE
| |
|
| |
| ; To set the Current Country
| |
|
| |
| MOV AH,38H ; Function Call -- Get/Set
| |
| ; Country Information
| |
| MOV AL,CountryID ; Country ID (-1 if >= 255)
| |
| MOV BX,CountryIDX ; Country ID (if AL=-1)
| |
| MOV DX,-1 ; Indicate set country code
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
| ; To get Country Information
| |
|
| |
| MOV AX,SEG Buffer
| |
| MOV DS,AX
| |
| MOV DX,OFFSET Buffer
| |
| MOV AH,38H
| |
| MOV AL,CountryID ; Country ID (-1 if >= 255)
| |
| ; (0 to get current country)
| |
| MOV BX,CountryIDX ; Country ID (if AL=-1)
| |
|
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV CountryCode,BX ; Save current Country Code
| |
|
| |
|
| |
| CountryCode DW ? ; Current country code
| |
|
| |
| CountryIDX DW ? ; Extended country code for input
| |
|
| |
| Buffer LABEL WORD ; Country information (see format below)
| |
| CountryID DB ? ; Country code for input
| |
|
| |
| COUNTRY INFORMATION
| |
|
| |
| DateFormat DW ? ; Date Format:
| |
| ; 0 = m d y order
| |
| ; 1 = d m y order
| |
| ; 2 = y m d order
| |
| $Symbol DB "????",0 ; Currency Symbol
| |
| ; example: "DM",0,?,?
| |
| Sep1000 DB "?",0 ; Thousands Separator
| |
| ; example: ",",0
| |
| Sep1 DB "?",0 ; Fractions Separator
| |
| ; example: ".",0
| |
| SepDate DB "?",0 ; Date Separator
| |
| ; example: "/",0
| |
| SepTime DB "?",0 ; Time Separator
| |
| ; example: ":",0
| |
| $Format DB ? ; Currency Format:
| |
| ; 0 = currency symbol, value
| |
| ; 1 = value, currency symbol
| |
| ; 2 = currency symbol, space, value
| |
| ; 3 = value, space, currency symbol
| |
| ; 4 = currency symbol is decimal separat
| |
| SigDigits DB ? ; Number of Significant Digits in Currency
| |
| TimeFormat DB ? ; Time Format:
| |
| ; 0 = 12 hour clock
| |
| ; 1 = 24 hour clock
| |
| UpperCaseAL@ DD ? ; Address of Routine to Upper Case AL
| |
| ; Only for values >=80H
| |
| SepData DB "?",0 ; Data List Separator
| |
| ; example: ",",0
| |
| Reserved DW 5 DUP(?) ; Reserved for future
| |
|
| |
| COMMENTS
| |
|
| |
| The date format has the following values and meaning:
| |
|
| |
| CODE DATE
| |
| 0=USA m d y
| |
| 1=EUROPE d m y
| |
| 2=JAPAN y m d
| |
|
| |
| Case Map Call Address: The register contents for the case map call are:
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | ON REGISTER |
| |
| | ENTRY CONTENTS |
| |
| +---------------------------------------------------------------------------+
| |
| | AL ASCII code of character to be converted to uppercase |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | ON REGISTER |
| |
| | RETURN CONTENTS |
| |
| +---------------------------------------------------------------------------+
| |
| | AL ASCII code of the uppercase input character |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| The case map call address is in a form suitable for a FAR call indirect.
| |
|
| |
| RETURNS
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location. Function Call 65H, (Get Extended Country Information), returns
| |
| more country information and is preferred.
| |
|
| |
| Setting the Current County Code by using this function call is not
| |
| recommended. The user can set it by placing a COUNTRY command in the
| |
| CONFIG.SYS file. The Country Code set by the user should not be changed.
| |
| The NLSFUNC DOS 4.00 extension must be installed to change the Current
| |
| Country.
| |
|
| |
| 39H --
| |
| CREATE SUBDIRECTORY (MKDIR)
| |
|
| |
| PURPOSE
| |
|
| |
| Creates the specified directory.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG DName ;Directory Name
| |
| MOV DS,AX
| |
| MOV DX,OFFSET DName
| |
| MOV AH,39H ;Function-Make a directory
| |
| INT 21H ;Issue request to DOS
| |
| JC Error
| |
|
| |
|
| |
| DName DB "?? .. ??",0 ; ASCIIZ Name
| |
| ; Example:
| |
| ; "c:\dir",0
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, DS:DX contains the address of an ASCIIZ string with drive and
| |
| directory path names. All directory levels other than the last one in the
| |
| name must exist before using this function. Only one directory level at a
| |
| time can be created with this function. The maximum length of the ASCIIZ
| |
| string is 64 characters.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| Network Access Rights: Requires Create access rights.
| |
|
| |
| 3AH --
| |
| REMOVE SUBDIRECTORY (RMDIR)
| |
|
| |
| PURPOSE
| |
|
| |
| Removes the specified directory.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG DName ;Directory name
| |
| MOV DS,AX
| |
| MOV DX,OFFSET DName
| |
| MOV AH,3AH ;Function-Remove directory
| |
| INT 21H ;Issue request to DOS
| |
| JC Error
| |
|
| |
|
| |
| DName DB "?? .. ??",0 ; ASCIIZ Name
| |
| ; example: "c:\dir",0
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, DS:DX contains the address of an ASCIIZ string with the drive and
| |
| directory path names. The specified directory is removed from the structure.
| |
| The current directory or a directory with files in it cannot be removed.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| Network Access Rights: Requires Create access rights.
| |
|
| |
| 3BH --
| |
| CHANGE THE CURRENT DIRECTORY (CHDIR)
| |
|
| |
| PURPOSE
| |
|
| |
| Changes the current directory to the specified directory.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG DName ;Directory name
| |
| MOV DS,AX
| |
| MOV DX,OFFSET DName
| |
| MOV AH,3BH ;Function -- Change directory
| |
| INT 21H ;Issue request to DOS
| |
| JC Error
| |
|
| |
|
| |
| DName DB "?? .. ??",0 ; ASCIIZ Name
| |
| ; example: "c:\dir",0
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, DS:DX contains the address of an ASCIIZ string with drive and
| |
| directory path names. The string is limited to 64 characters and cannot
| |
| contain a network path. If any member of the directory path does not exist,
| |
| the directory path is not changed. Otherwise, the current directory is set
| |
| to the ASCIIZ string.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| 3CH --
| |
| CREATE A FILE (CREAT)
| |
|
| |
| PURPOSE
| |
|
| |
| Creates a new file or shortens an old file to 0 length in preparation for
| |
| writing.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG FName ;File name
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FName
| |
| MOV AH,3CH ;Function -- Create a File
| |
| MOV CX,Attribute ; Attribute of the file
| |
| ; Allowed values
| |
| ; 0001H=Read only
| |
| ; 0002H=Hidden
| |
| ; 0004H=System
| |
| ; 0008H=Volume label
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV Handle,AX ; Save file handle for
| |
|
| |
|
| |
| FName DB "?? .. ??",0 ; ASCIIZ Name
| |
| ; example: "c:\dir\file.ext",0
| |
| Handle DW ? ; File handle
| |
| Attribute DW ? ; Attributes for directory entry
| |
|
| |
| COMMENTS
| |
|
| |
| If the file did not exist, the file is created in the appropriate directory
| |
| and the file is given the read/write access code. The file is opened for
| |
| read/write, the read/write pointer is set to the first byte of the file and
| |
| the handle is returned in AX. Note that function call 43H (Change File Mode)
| |
| can be used later to change the file's attribute.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| This function does not replace an existing volume label. You must delete the
| |
| existing volume label before issuing this call.
| |
|
| |
| Network Access Rights: Requires Create access rights.
| |
|
| |
| 3DH --
| |
| OPEN A FILE
| |
|
| |
| PURPOSE
| |
|
| |
| Opens the specified file.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG FName ; File name
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FName
| |
| MOV AH,3DH ; Function -- Open a File
| |
| MOV AL,OpenMode
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV Handle,AX ; Save file handle for following operations
| |
|
| |
|
| |
| FName DB "?? .. ??",0 ; ASCIIZ Name
| |
| ; example: "c:\dir\file.ext",0
| |
| Handle DW ? ; File Handle
| |
| OpenMode DB ? ; Open mode
| |
|
| |
| COMMENTS
| |
|
| |
| The read/write pointer is set at the first byte of the file and the record
| |
| size of the file is 1 byte. The read/write pointer can be changed with
| |
| function call 42H. The returned file handle must be used for subsequent
| |
| input and output to the file. The file's date and time can be obtained or
| |
| set through call 57H, and its attribute can be obtained through call 43H.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| NOTES:
| |
|
| |
| 1. This call opens any normal or hidden file whose name matches the name
| |
| specified.
| |
|
| |
| 2. Device names cannot end in a colon.
| |
|
| |
| 3. When a file is closed, any sharing restrictions placed on it by the open
| |
| are canceled.
| |
|
| |
| 4. File sharing must be loaded, or the file must be a network file for the
| |
| sharing modes to function. Refer to the SHARE command.
| |
|
| |
| 5. The file read-only attribute can be set when creating the file using
| |
| extended FCBs or specifying the appropriate attribute in CX and using the
| |
| CHMOD interrupt 21H function call or the DOS 4.00 ATTRIB command.
| |
|
| |
| 6. If the file is inherited by the subordinate process, all sharing and
| |
| access restrictions are also inherited.
| |
|
| |
| 7. If an open file handle is duplicated by either of the DUP function calls,
| |
| all sharing and access restrictions are also duplicated.
| |
|
| |
| OPEN MODE
| |
|
| |
| The open mode is defined in AL and consists of four bit-oriented fields:
| |
|
| |
| INHERITANCE FLAG Specifies if the opened file is inherited by a
| |
| subordinate process.
| |
| SHARING MODE FIELD Defines which operations other processes can perform on
| |
| the file.
| |
| RESERVED FIELD
| |
| ACCESS FIELD Defines which operations the current process can perform
| |
| on the file.
| |
|
| |
| BIT FIELDS
| |
|
| |
| The bit fields are mapped as follows:
| |
|
| |
| <I> < S > <R> < A >
| |
| Open Mode bits 7 6 5 4 3 2 1 0
| |
|
| |
| I Inheritance flag
| |
|
| |
| If I = 0; File is inherited by subordinate processes.
| |
| If I = 1; File is private to the current process.
| |
|
| |
| S Sharing Mode
| |
|
| |
| The file is opened as follows:
| |
|
| |
| S = 000 -- Compatibility mode
| |
| S = 001 -- DenyRead/Write mode (exclusive)
| |
| S = 010 -- DenyWrite mode
| |
| S = 011 -- DenyRead mode
| |
| S = 100 -- DenyNone mode
| |
|
| |
| Any other combinations are invalid.
| |
|
| |
| When opening a file, you must inform DOS 4.00 which operations any
| |
| other processes, in sharing mode, can perform on the file.
| |
|
| |
| The default, compatibility mode, denies all other computers in a
| |
| network access to the file. If other processes can continue to read
| |
| the file while your process is operating on it, specify DenyWrite.
| |
| DenyWrite prohibits writing by other processes, but allows reading.
| |
|
| |
| Similarly, you must specify which operations, or access modes, your
| |
| process can perform. The default access mode, ReadWrite, causes the
| |
| open request to fail if another process on the computer or any other
| |
| computer on a network has the file opened with any sharing mode other
| |
| than DenyNone. If you intend to read from the file only, your Open
| |
| will succeed unless all other processes have specified DenyNone or
| |
| DenyWrite. File sharing requires cooperation of both sharing
| |
| processes.
| |
|
| |
| R Reserved (set this bit field to 0).
| |
|
| |
| A Access
| |
|
| |
| The file access is assigned as follows:
| |
|
| |
| If A = 000; Read access
| |
| If A = 001; Write access
| |
| If A = 010; Read/Write access
| |
|
| |
| Any other combinations are invalid.
| |
|
| |
| Network Access Rights: If the Access field (A) of the Open mode field (AL)
| |
| is equal to:
| |
|
| |
| 000 Requires Read access rights
| |
|
| |
| 001 Requires Write access rights
| |
|
| |
| 010 Requires Read/Write access rights
| |
|
| |
| COMPATIBILITY MODE
| |
|
| |
| A file is considered to be in compatibility mode if the file is opened by:
| |
|
| |
| Any of the CREATE function calls
| |
| An FCB function call
| |
| A handle function call with compatibility mode specified.
| |
|
| |
| A file can be opened any number of times in compatibility mode by a single
| |
| process, provided that the file is not currently open under one of the other
| |
| four sharing modes. If the file is marked read-only, and is open in
| |
| DenyWrite sharing mode with Read Access, the file may be opened in
| |
| Compatibility Mode with Read Access. If the file was successfully opened in
| |
| one of the other sharing modes and an attempt is made to open the file again
| |
| in Compatibility Mode, an interrupt 24H is generated to signal this error.
| |
| The base interrupt 24H error indicates DRIVE NOT READY, and the extended
| |
| error indicates a SHARING VIOLATION.
| |
|
| |
| SHARING MODES
| |
|
| |
| The sharing modes for a file opened in compatibility mode are changed by DOS
| |
| 4.00 depending on the read-only attribute of the file. This allows sharing
| |
| of read-only files.
| |
|
| |
| +---------------------------------------------------+
| |
| | READ-ONLY |
| |
| | FILE OPENED BY ACCESS SHARING MODE |
| |
| +---------------------------------------------------+
| |
| | FCB Read-Only DenyWrite |
| |
| +---------------------------------------------------+
| |
| | Handle Read Read-Only DenyWrite |
| |
| +---------------------------------------------------+
| |
| | Handle Write Error ----- |
| |
| +---------------------------------------------------+
| |
| | Handle Error ----- |
| |
| | Read/Write |
| |
| +---------------------------------------------------+
| |
|
| |
| +---------------------------------------------------+
| |
| | NOT READ-ONLY |
| |
| | FILE OPENED BY ACCESS SHARING MODE |
| |
| +---------------------------------------------------+
| |
| | FCB Read/Write Compatibility |
| |
| +---------------------------------------------------+
| |
| | Handle Read Read Compatibility |
| |
| +---------------------------------------------------+
| |
| | Handle Write Write Compatibility |
| |
| +---------------------------------------------------+
| |
| | Handle Read/Write Compatibility |
| |
| | Read/Write |
| |
| +---------------------------------------------------+
| |
|
| |
| DENYREAD/WRITE MODE (EXCLUSIVE)
| |
|
| |
| If a file is successfully opened in DenyRead/Write mode, access to the file
| |
| is exclusive. A file currently open in this mode cannot be opened again in
| |
| any sharing mode by any process (including the current process) until the
| |
| file is closed.
| |
|
| |
| DENYWRITE MODE
| |
|
| |
| A file successfully opened in DenyWrite sharing mode, prevents any other
| |
| write access opens to the file (A = 001 or 010) until the file is closed. An
| |
| attempt to open a file in DenyWrite mode is unsuccessful if the file is open
| |
| with a write access.
| |
|
| |
| DENYREAD MODE
| |
|
| |
| A file successfully opened in DenyRead sharing mode, prevents any other read
| |
| sharing access opens to the file (A = 000 or 010) until the file is closed.
| |
| An attempt to open a file in DenyRead sharing mode is unsuccessful if the
| |
| file is open in Compatibility mode or with a read access.
| |
|
| |
| DENYNONE MODE
| |
|
| |
| A file successfully opened in DenyNone mode, places no restrictions on the
| |
| read/write accessibility of the file. An attempt to open a file in DenyNone
| |
| mode is unsuccessful if the file is open in Compatibility mode.
| |
|
| |
| When accessing files that reside on a network disk, no local buffering is
| |
| done when files are opened in any of the following sharing modes:
| |
|
| |
| DenyRead
| |
| DenyNone.
| |
|
| |
| Therefore, in a network environment, DenyRead/Write sharing mode,
| |
| Compatibility sharing mode, and DenyWrite mode opens are buffered locally.
| |
|
| |
| The following sharing matrix shows the results of opening, and subsequently
| |
| attempting to reopen the same file using all combinations of access and
| |
| sharing modes:
| |
|
| |
| Y :2nd,3rd,...open is allowed
| |
| N :2nd,3rd,...open is denied
| |
| DRW :DenyRead/Write Mode (Exclusive)
| |
| DW :DenyWrite Mode
| |
| DR :DenyRead Mode
| |
| ALL :Read/Write Mode
| |
| I :Read Only Access
| |
| O :Write Only Access
| |
| IO :Read/Write Access
| |
|
| |
| 3EH --
| |
| CLOSE A FILE HANDLE
| |
|
| |
| PURPOSE
| |
|
| |
| Closes the specified file handle.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,3EH ; Function Call --
| |
| ; Close a Handle
| |
| MOV BX,Handle
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| Handle DW ? ; File Handle (from Open / Create)
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, BX contains the file handle that was returned by Open or Create.
| |
| On return, the file is closed, the directory is updated, and all internal
| |
| buffers for that file are flushed.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| 3FH --
| |
| READ FROM A FILE OR DEVICE
| |
|
| |
| PURPOSE
| |
|
| |
| Transfers the specified number of bytes from a file into a buffer location.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG Buffer ; Address data buffer
| |
| MOV DS,AX
| |
| MOV DX,OFFSET Buffer
| |
| MOV AH,3FH ; Function -- Read from a file
| |
| MOV BX,Handle
| |
| MOV CX,BufSize ; Buffer size
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| CMP AX,0 ; At End Of File?
| |
| JE EOF ; Yes!
| |
| MOV SizeRead,AX ; Save Amount Read
| |
|
| |
| N EQU 512 ; Typical buffer size
| |
| Handle DW ? ; File Handle (from Open /Create)
| |
| BufSize DW N ; Buffer Size, N is
| |
| Buffer DB N DUP(?) ; Data Buffer
| |
| SizeRead DW ? ; Amount of Data in Buffer
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, BX contains the file handle. CX contains the number of bytes to
| |
| read. DS:DX contains the buffer address. On return, AX contains the number
| |
| of bytes read.
| |
|
| |
| This function call attempts to transfer (CX) bytes from a file into a buffer
| |
| location. It is not guaranteed that all bytes will be read. For example,
| |
| when DOS 4.00 reads from the keyboard, at most one line of text is
| |
| transferred. If this read is performed from the standard input device, the
| |
| input can be redirected. If the value in AX is 0, then the program has tried
| |
| to read from the end of file.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| Network Access Rights: Requires Read access rights.
| |
|
| |
| 40H --
| |
| WRITE TO A FILE OR DEVICE
| |
|
| |
| PURPOSE
| |
|
| |
| Transfers the specified number of bytes from a buffer into a specified file.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG Buffer ;Data Buffer
| |
| MOV DS,AX
| |
| MOV DX,OFFSET Buffer
| |
| MOV CX,BufSize
| |
| MOV AH,40H ;Function-Write to a File
| |
| MOV BX,Handle
| |
| MOV DX,OFFSET Buffer
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| CMP AX,CX ; Disk Full?
| |
| JB FullDisk ; Yes!
| |
|
| |
| N EQU 512 ; Typical buffer size
| |
| Handle DW ? ; File Handle (from Open / Create)
| |
| BufSize DW N ; Buffer Size
| |
| Buffer DB N DUP(?) ; Data Buffer
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, BX contains the file handle. CX contains the number of bytes to
| |
| write. DS:DX contains the address of the data to write.
| |
|
| |
| This function call attempts to transfer (CX) bytes from a buffer into a file.
| |
| AX returns the number of bytes actually written. If the carry flag is not
| |
| set and this value is not the same as the number requested (in CX), it should
| |
| be considered an error. Although no error code is returned, your program can
| |
| compare these values. Normally, the reason for the error is a full disk. If
| |
| this write is performed to the standard output device, the output can be
| |
| redirected.
| |
|
| |
| To truncate a file at the current position of the file pointer, set the
| |
| number of bytes (CX) to 0 before issuing the interrupt 21H. The file pointer
| |
| can be moved to the desired position by reading, writing, and performing
| |
| function call 42H, (Move File Read/Write Pointer.)
| |
|
| |
| If the file is read-only, the write to the file or device is not performed.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| Network Access Rights: Requires Write access rights.
| |
|
| |
| 41H --
| |
| DELETE A FILE FROM A SPECIFIED DIRECTORY (UNLINK)
| |
|
| |
| PURPOSE
| |
|
| |
| Removes a directory entry associated with a filename.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG FName ; File Name
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FName
| |
| MOV AH,41H ; Function-Delete a File
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| FName DB "?? .. ??",0 ; ASCIIZ Name
| |
| ; example: "c:\dir\File.ext",0
| |
|
| |
| COMMENTS
| |
|
| |
| Global filename characters are not allowed in any part of the ASCIIZ string.
| |
| Read-only files cannot be deleted by this call. To delete a read-only file,
| |
| you can first use call 43H to change the file's read-only attribute to 0,
| |
| then delete the file.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| Network Access Rights: Requires Create access rights.
| |
|
| |
| 42H --
| |
| MOVE FILE READ WRITE POINTER (LSEEK)
| |
|
| |
| PURPOSE
| |
|
| |
| Moves the read/write pointer according to the method specified.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,42H ; Function Call --
| |
| ; Move Read/Write Pointer
| |
| MOV AL,Method ; Method of Positioning:
| |
| ; 0 = From Beginning of File
| |
| ; (BOF)
| |
| ; 1 = From Current Position
| |
| ; 2 = From End of File (EOF)
| |
| MOV BX,Handle ; Select File
| |
| MOV DX,WORD PTR Position+0 ; New Position = Position + METHOD
| |
| MOV CX,WORD PTR Position+2
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV WORD PTR Position+0,AX ; Set new File Position
| |
| MOV WORD PTR Position+2,DX
| |
|
| |
|
| |
| Handle DW ? ; File Handle (from Open /
| |
| ; Create)
| |
| Position DD ? ; File Offset (may be
| |
| ; negative)
| |
| Method DB ?
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, AL contains a method value. BX contains the file handle. CX:DX
| |
| contains the desired offset in bytes with CX containing the most significant
| |
| part. On return, DX:AX contains the new location of the pointer with DX
| |
| containing the most significant part if the carry flag is not set.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| This function call moves the read/write pointer according to the following
| |
| methods:
| |
|
| |
| +---------+-----------------------------------------------------------------+
| |
| | AL | DESCRIPTION |
| |
| +---------+-----------------------------------------------------------------+
| |
| | 0 | The pointer is moved CX:DX bytes (offset) from the beginning of |
| |
| | | the file. |
| |
| +---------+-----------------------------------------------------------------+
| |
| | 1 | The pointer is moved to the current location plus offset. |
| |
| +---------+-----------------------------------------------------------------+
| |
| | 2 | The pointer is moved to the end-of-file plus offset. This |
| |
| | | method can be used to determine file's size. |
| |
| +---------+-----------------------------------------------------------------+
| |
|
| |
| NOTE: If an LSEEK operation is performed on a file that resides on a network
| |
| disk that is open in either DenyRead or DenyNone sharing mode, the
| |
| read/write pointer information is adjusted on the computer where the
| |
| file actually exists. If the file is opened in any other sharing
| |
| mode, the read/write pointer information is kept on the remote
| |
| computer.
| |
|
| |
| 43H --
| |
| CHANGE FILE MODE (CHMOD)
| |
|
| |
| PURPOSE
| |
|
| |
| Changes the file mode of the specified file.
| |
|
| |
| EXAMPLE
| |
|
| |
| ; To Get Attributes
| |
|
| |
| MOV AX,SEG FName ;File Name
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FName ;DS:DX points to ASCIIZ path name
| |
| MOV AL,0 ;Indicate get
| |
| MOV AH,43H ;Function-Change File Mode
| |
| INT 21H ;Issue request to DOS
| |
| JC Error ;Error code in AX
| |
| MOV Attribute,CX ;Save Attribute
| |
|
| |
| ; To Set Attributes
| |
|
| |
| MOV AX,SEG FName ;File Name
| |
| MOV DS,AX
| |
| MOV DX,OFFSET FName ;DS:DX points to ASCIIZ path name
| |
| MOV AL,1 ;Indicate set
| |
| MOV AH,43H ;Function-Change File Mode
| |
| MOV CX,Attribute ;Set Attribute
| |
| INT 21H ;Issue request to DOS
| |
| JC Error ;Error code in AX
| |
|
| |
|
| |
| Fname DB 64 Dup (0) ;ASCIIZ Name
| |
| ; example: "c:\dir\File.ext",0
| |
| Attribute DW ? ;File Attribute
| |
| ; example: 0001H to set Read-Only
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, AL contains a function code, and DS:DX contains the address of an
| |
| ASCIIZ string with the drive, path, and filename.
| |
|
| |
| If AL contains 01H, the file's attribute is set to the attribute in CX. See
| |
| "The Disk Directory" on page 2-3 for the attribute byte description. If AL
| |
| is 00H the file's current attribute is returned in CX.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| NOTE: Only the Archive (20H), Read-Only (01H), System (04H) and Hidden (02H)
| |
| bits can be changed. All other bits of CX must be 0, otherwise, an
| |
| error may be indicated.
| |
|
| |
| Network Access Rights: To change the archive bit (AL=20H), no access rights
| |
| are required. To change any other bit, Create access rights are required.
| |
|
| |
| 44H --
| |
| I/O CONTROL FOR DEVICES
| |
|
| |
| PURPOSE
| |
|
| |
| Sets or gets device information associated with open device handles, or sends
| |
| control strings to the device handle or receives control strings from the
| |
| device handle.
| |
|
| |
| See Appendix C for full details on this function call.
| |
|
| |
| 45H --
| |
| DUPLICATE A FILE HANDLE (DUP)
| |
|
| |
| PURPOSE
| |
|
| |
| Returns a new file handle for an open file that refers to the same file at
| |
| the same position.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,45H ; Function Call --
| |
| ; Duplicate a Handle
| |
| MOV BX,Handle ; Select File
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV NewHandle,AX ; Save New Handle
| |
|
| |
|
| |
| Handle DW ? ; File Handle (from Open / Create)
| |
| NewHandle DW ? ; File Handle that duplicates Handle
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, BX contains the file handle. On return, AX contains the returned
| |
| file handle.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| NOTE: If you move the read/write pointer of either handle by a read, write,
| |
| or LSEEK function call, the pointer for the other handle is also
| |
| changed.
| |
|
| |
| 46H --
| |
| FORCE A DUPLICATE OF A HANDLE (FORCDUP)
| |
|
| |
| PURPOSE
| |
|
| |
| Forces the handle in CX to refer to the same file at the same position as the
| |
| handle in BX.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,46H ; Function Call --
| |
| ; Force Duplicate a Handle
| |
| MOV BX,Handle ; Select file
| |
| MOV CX,NewHandle ; Select new definition of File
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| Handle DW ? ; File Handle (from Open/Create)
| |
| NewHandle DW ? ; File Handle that duplicates Handle
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, BX contains the file handle. CX contains a second file handle. On
| |
| return, the CX file handle refers to the same file at the same position as
| |
| the BX file handle. If the CX file handle was an open file, it is closed
| |
| first. If you move the read/write pointer of either handle, the pointer for
| |
| the other handle is also changed.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| 47H --
| |
| GET CURRENT DIRECTORY
| |
|
| |
| PURPOSE
| |
|
| |
| Places the full path name (starting from the root directory) of the current
| |
| directory for the specified drive in the area pointed to by DS:SI.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG DName ; Directory Name Buffer
| |
| MOV DS,AX
| |
| MOV SI,OFFSET DName ; OS:SI points to buffer
| |
| MOV DL,Drive ; Select Drive
| |
| MOV AH,47H ; Function-Get Current Dir
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| Drive DB ? ; Drive (0=current, 1=A:, 2=b:, ...)
| |
| DName DB 64 DUP(?) ; ASCIIZ Directory Name Returned
| |
| ; example: "dir1\dir2",0
| |
|
| |
| COMMENTS
| |
|
| |
| The drive letter is not part of the returned string. The string does not
| |
| begin with a backslash and is terminated by a byte containing 00H.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| 48H --
| |
| ALLOCATE MEMORY
| |
|
| |
| Allocates the requested number of paragraphs of memory.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,48H ; Function Call --
| |
| ; Allocate Memory
| |
| MOV BX,Paragraphs ; Paragraphs Desired
| |
| INT 21H ; Issue request to DOS
| |
| JNC Done
| |
| MOV AH,48H ; Function Call --
| |
| ; Allocate memory
| |
| ; BX set to largest available memory
| |
| INT 21H ; Issue request to DOS
| |
| Done:
| |
| MOV BlockSeg,AX ; Save BlockSeg of memory
| |
| MOV Paragraphs,BX
| |
|
| |
|
| |
| Paragraphs DW ? ; Size requested in paragraphs
| |
| ; (Bytes allocated is 16 * Paragraphs)
| |
| BlockSeg DW ? ; BlockSeg address of allocated memory
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, BX contains the number of paragraphs requested. On return, AX:0
| |
| points to the allocated memory block. If the allocation fails, BX returns
| |
| the size of the largest block of memory available in paragraphs.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| 49H --
| |
| FREE ALLOCATED MEMORY
| |
|
| |
| PURPOSE
| |
|
| |
| Frees the specified allocated memory.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,49H ; Function Call -- Free Memory
| |
| MOV ES,BlockSeg ; Set address to free
| |
| INT 21H ; Issue request to DOS
| |
| JC Error
| |
|
| |
|
| |
| BlockSeg DW ? ; BlockSeg address of allocated memory
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, ES contains the segment of the block to be returned to the system
| |
| pool. On return, the block of memory is returned to the system pool.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| 4AH --
| |
| MODIFY ALLOCATED MEMORY BLOCKS (SETBLOCK)
| |
|
| |
| PURPOSE
| |
|
| |
| Modifies allocated memory blocks to contain the new specified block size.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,4AH ; Function Call --
| |
| ; Modify Allocated Memory; allocate memory
| |
| MOV ES,BlockSeg ; Set address to free
| |
| MOV BX,BlockSize ; New size (may be larger or smaller)
| |
| INT 21H ; Issue request to DOS
| |
| JNC Done
| |
| MOV AH,4AH ; Function Call --
| |
| ; Allocate memory
| |
| ; BX set to largest available Size
| |
| INT 21H ; Issue request to DOS
| |
| Done:
| |
| MOV Size,BX
| |
|
| |
|
| |
| BlockSeg DW ? ; Segment address of allocated memory
| |
| BlockSize DW ? ; Size requested in paragraphs
| |
| ; (Bytes allocated is 16 * Size)
| |
|
| |
| COMMENTS
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| NOTE: This call is often used to set the size of a program before using
| |
| function call 31H (Terminate Process and Remain Resident). Use the
| |
| program segment prefix. This value can be obtained using function
| |
| call 62H (Get Program Segment Prefix Address). Another use is to
| |
| release memory to prepare for using function call 4BH (Load or Execute
| |
| a Program).
| |
|
| |
| 4BH --
| |
| LOAD OR EXECUTE A PROGRAM (EXEC)
| |
|
| |
| PURPOSE
| |
|
| |
| Allows a program to load another program into memory and may choose to begin
| |
| execution of it.
| |
|
| |
| EXAMPLE
| |
|
| |
| ; To Execute a Program
| |
|
| |
| MOV AH,4BH ; Function Call -- Execute a Program
| |
| MOV AL,0 ; Indicate execute program
| |
| MOV CX,SEG Parms ; Program parameters
| |
| MOV ES,CX
| |
| MOV BX,OFFSET Parms : ES:BX points to parameter block
| |
| MOV CX,SEG PName ; Program name
| |
| MOV DS,CX
| |
| MOV DX,OFFSET PName ; DS:DX points to program name
| |
| MOV WORD PTR StackSave+0,SP ; Save stack pointer
| |
| MOV WORD PTR StackSave+2,SS
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| ; Note: All Registers (except CS:IP) Destroyed
| |
|
| |
| ; Program Runs here
| |
|
| |
| CLI ; Protect from stack usage
| |
| MOV SS,WORD PTR StackSave+2 ; Restore stack pointer
| |
| MOV SP,WORD PTR StackSave+0
| |
| STI ; Enable interrupts
| |
| MOV AH,4DH ; Function Call -- Get Return Code
| |
| INT 21H ; Issue request to DOS
| |
| MOV RetCode,AX ; Save return code
| |
|
| |
| ; To Load an Overlay
| |
| MOV AH,4BH ; Function Call -- Execute a Program
| |
| MOV AL,3 ; Indicate load overlay
| |
| MOV CX,SEG OParms ; Overlay parameters
| |
| MOV ES,CX
| |
| MOV BX,OFFSET OParms ; ES:BX points to parameter block
| |
| MOV CX,SEG PName ; Overlay name
| |
| MOV DS,CX
| |
| MOV DX,OFFSET PName ; DS:DX points to overlay filename
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
| PName DB 64 Dup (0) ; ASCIIZ Name
| |
| ; example: "c:\dir\File.ext",0
| |
| Parms LABEL WORD ; Program parameters
| |
| Env@ DW ? ; Environment segment address
| |
| ; Value of 0000H indicates copy EXEC'ers
| |
| ; Environment
| |
| Cmd@ DD ? ; Command line address
| |
| FCB1@ DD ? ; FCB Image to set to New PSP+5CH
| |
| FCB2@ DD ? ; FCB Image to set to New PSP+6CH
| |
|
| |
| StackSave DD ? ; Stack pointer save area
| |
| RetCode DW ? ; Program return code
| |
| ; (see function code 4DH for more informatio
| |
| OParms LABEL WORD ; Overlay parameters
| |
| Load@ DW ? ; Overlay load segment address
| |
| RelocFactor DW ? ; Relocation factor to apply (for .EXE files
| |
|
| |
| COMMENTS
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location. Refer to "Responding to Errors" on page B-5 and "Extended Error
| |
| Codes" on page B-5 for more information on the codes returned from function
| |
| call 59H.
| |
|
| |
| The following function values are allowed in AL:
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | FUNCTION |
| |
| | VALUE DESCRIPTION |
| |
| +---------------------------------------------------------------------------+
| |
| | 00H Load and execute the program. A program segment prefix is |
| |
| | established for the program; terminate and Ctrl-Break addresses |
| |
| | are set to the instruction after the EXEC system call. |
| |
| | |
| |
| | NOTE: When control is returned, all registers are changed, |
| |
| | including the stack. You must restore SS, SP, and any |
| |
| | other required registers before proceeding. |
| |
| +---------------------------------------------------------------------------+
| |
| | 03H Load, do not create the program segment prefix, and do not |
| |
| | begin execution. This is useful in loading program overlays. |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| All open files of a process are duplicated in the newly created process after
| |
| an EXEC, unless the file was opened with the inheritance bit set to 1. This
| |
| means that the parent process has control over the meanings of standard
| |
| input, output, auxiliary, and printer devices. The parent could, for
| |
| example, write a series of records to a file, open the file as standard
| |
| input, open a listing file as standard output, and then execute a sort
| |
| program that takes its input from standard input and writes to standard
| |
| output.
| |
|
| |
| Also inherited (or copied from the parent) is an "environment." This is a
| |
| block of text strings (less than 32KB total) that conveys various
| |
|
| |
| configuration parameters. The following is the format of the environment
| |
| (always on a paragraph boundary):
| |
|
| |
| +---------------------------------------------------------------------------+
| |
| | Byte ASCIIZ string 1 |
| |
| +---------------------------------------------------------------------------+
| |
| | Byte ASCIIZ string 2 |
| |
| +---------------------------------------------------------------------------+
| |
| | ... |
| |
| +---------------------------------------------------------------------------+
| |
| | Byte ASCIIZ string n |
| |
| +---------------------------------------------------------------------------+
| |
| | Byte of 0 |
| |
| +---------------------------------------------------------------------------+
| |
|
| |
| Typically the environment strings have the form:
| |
|
| |
| parameter=value
| |
|
| |
| Following the byte of 0 in the environment is a WORD that indicates the
| |
| number of other strings following. Following this is a copy of the DS:DX
| |
| filename passed to the child process. For example, the string VERIFY=ON
| |
| could be passed. A 0 value of the environment address causes the newly
| |
| created process to inherit the original environment unchanged. The segment
| |
| address of the environment is placed at offset 2CH of the program segment
| |
| prefix for the program being invoked.
| |
|
| |
| Errors codes are returned in AX. Refer to "Responding to Errors" on page B-5
| |
| and "Extended Error Codes" on page B-5 for more information on the codes
| |
| returned.
| |
|
| |
| NOTE: When your program received control, all available memory was allocated
| |
| to it. You must free some memory (see call 4AH) before EXEC can load
| |
| the program you are invoking. Normally, you would shrink down to the
| |
| minimum amount of memory you need, and free the rest.
| |
|
| |
| 4CH --
| |
| TERMINATE A PROCESS (EXIT)
| |
|
| |
| PURPOSE
| |
|
| |
| Terminates the current process and transfers control to the invoking process.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,4CH ; Function Call -- Terminate a Process
| |
| MOV AL,ErrorCode ; Set ERRORLEVEL
| |
| INT 21H ; Issue request to DOS
| |
| INT 20H ; Be safe if running on PC/DOS 1.1
| |
|
| |
|
| |
| ErrorCode DB ? ; Error Code (sets ERRORLEVEL if EXEC'ed
| |
| ; by COMMAND.COM)
| |
|
| |
| COMMENTS
| |
|
| |
| In addition, a return code can be sent. The return code can be interrogated
| |
| by the batch subcommands IF and ERRORLEVEL and by the wait function call 4DH.
| |
| All files opened by this process are closed.
| |
|
| |
| 4DH --
| |
| GET RETURN CODE OF A SUBPROCESS (WAIT)
| |
|
| |
| PURPOSE
| |
|
| |
| Gets the return code specified by another process either through function
| |
| call 4CH or function call 31H. It returns the Exit code only once.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,4DH ; Function Call -- Get Return Code
| |
| INT 21H ; Issue request to DOS
| |
| MOV RetCode,AX ; Save return code
| |
|
| |
| RetCode LABEL WORD ; Program return code
| |
| ExitCode DB ? ; ERRORLEVEL value
| |
| ExitType DB ? ; Method used to exit:
| |
| ; 00H -- for normal termination
| |
| ; 01H -- for termination by Ctrl-Break
| |
| ; 02H -- for termination as a result
| |
| ; of a critical device error
| |
| ; 03H -- for termination by call 31H
| |
|
| |
| COMMENTS
| |
|
| |
| The low byte of the exit code contains the information sent by the exiting
| |
| routine.
| |
|
| |
| 4EH --
| |
| FIND FIRST MATCHING FILE (FIND FIRST)
| |
|
| |
| PURPOSE
| |
|
| |
| Finds the first filename that matches the specified file specification.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,1AH ; Function Call -- Set DTA Address
| |
| MOV CX,SEG DTA ; Address buffer for found file
| |
| MOV DS,CX
| |
| MOV DX,OFFSET DTA
| |
| INT 21H ; Issue request to DOS
| |
| MOV AH,4EH ; Function Call -- ASCIIZ Find First
| |
| MOV CX,SEG FName ; Directory or filename
| |
| MOV DS,CX
| |
| MOV DX,OFFSET FName ; DS:DX points to ASCII filename
| |
| MOV CX,Attribute ; Set Match Attribute
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| DTA LABEL BYTE ; Find return information
| |
| DB 21 DUP(0) ; Reserved for DOS 4.00 to continu
| |
| FileAttr DB ? ; Matched files attribute low byte
| |
| FileTime DW ? ; File time
| |
| FileDate DW ? ; File date
| |
| FileSize DD ? ; File size
| |
| FileNameExt DB "????????.???",0 ; Filename and extension
| |
|
| |
| FName DB 64 DUP (0) ; ASCIIZ Name
| |
| ; example: "c:\dir\*.*",0
| |
| Attribute DW ? ; Select files attribute
| |
| ; Combination of following:
| |
| ; 0002H=Hidden
| |
| ; 0004H=System
| |
| ; 0008H=Volume label
| |
| ; 0010H=Directory
| |
|
| |
| NOTES:
| |
|
| |
| If an extended FCB is used, the following search pattern is used:
| |
|
| |
| 1. If the attribute is 0, only normal file entries are found. Entries for
| |
| volume label, sub-directories, hidden and system files are not returned.
| |
|
| |
| 2. If the attribute field is set for hidden or system files, or directory
| |
| entries, it is to be considered as an inclusive search. All normal file
| |
| entries plus all entries matching the specified attributes are returned.
| |
| To look at all directory entries except the volume label, the attribute
| |
| byte may be set to hidden + system + directory (all 3 bits on).
| |
|
| |
| 3. If the attribute field is set for the volume label, it is considered an
| |
| exclusive search, and only the volume label entry is returned.
| |
|
| |
| COMMENTS
| |
|
| |
| The filename in DS:DX can contain global filename characters. The ASCIIZ
| |
| string cannot contain a network path. See function call 11H (Search for
| |
| First Entry) for a description of how the attribute bits are used for
| |
| searches.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location. Refer to "Responding to Errors" on page B-5 and "Extended Error
| |
| Codes" on page B-5 for more information on the codes returned from function
| |
| call 59H.
| |
|
| |
| NOTE: The name and extension of file found is returned as an ASCIIZ string.
| |
| All blanks are removed from the name and extension, and, if an
| |
| extension is present, it is preceded by a period.
| |
|
| |
| 4FH --
| |
| FIND NEXT MATCHING FILE (FIND NEXT)
| |
|
| |
| PURPOSE
| |
|
| |
| Finds the next directory entry matching the name that was specified on the
| |
| previous Find First or Find Next function call.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,1AH ; Function Call -- Set DTA Address
| |
| MOV CX,SEG DTA ; Address buffer for found file
| |
| MOV DS,CX
| |
| MOV DX,OFFSET DTA
| |
| INT 21H ; Issue request to DOS
| |
| MOV AH,4FH ; Function Call -- Find next
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| DTA LABEL BYTE " ; Find Return Information
| |
| DB 21 DUP(0) " ; Reserved for DOS to Continue Find
| |
| " ; Set by Find First or Previous Fin
| |
| FileAttr DB ? " ; Matched Files Attribute Low Byte
| |
| FileTime DW ? " ; File Time
| |
| FileDate DW ? " ; File Date
| |
| FileSize DD ? " ; File Size
| |
| FileNameExt DB "????????.???",0 ; File Name and Extension
| |
|
| |
| COMMENTS
| |
|
| |
| If a matching file is found, the DTA is set as described in call 4EH (Find
| |
| First Matching File (FIND FIRST)). If no more matching files are found, an
| |
| error code is returned.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location.
| |
|
| |
| 54H --
| |
| GET VERIFY SETTING
| |
|
| |
| PURPOSE
| |
|
| |
| Returns the value of the verify flag.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,54H ; Function Call -- Get VERIFY Setting
| |
| INT 21H ; Issue request to DOS
| |
| MOV VERIFY,AL ; Save VERIFY State
| |
|
| |
| VERIFY DB ? ; VERIFY State:
| |
| ; 0 = OFF
| |
| ; 1 = ON
| |
|
| |
| COMMENTS
| |
|
| |
| On return, AL returns 00H if verify is OFF, 01H if verify is ON. Note that
| |
| the verify switch can be set through call 2EH (Set/Reset Verify Switch).
| |
|
| |
| 56H --
| |
| RENAME A FILE
| |
|
| |
| PURPOSE
| |
|
| |
| Renames the specified file.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,56H ; Function Call -- ASCIIZ Rename File
| |
| MOV CX,SEG FName ; File Name
| |
| MOV DS,CX
| |
| MOV DX,OFFSET FName ; DS:DX points to original name
| |
| MOV CX,SEG NewName ; New File Name
| |
| MOV ES,CX
| |
| MOV DI,OFFSET NewName ; ES:DI points to rename
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| FName DB 64 DUP (0) ; ASCIIZ Name
| |
| ; example: "c:\dir\abc.lst",0
| |
| NewName DB 64 DUP (0) ; ASCIIZ Name
| |
| ; example: "\dir\xyz.lst",0
| |
|
| |
| COMMENTS
| |
|
| |
| If a drive is used in the NewName string, it must be the same as the drive
| |
| specified or implied in the Name string. The directory paths need not be the
| |
| same, allowing a file to be moved to another directory and renamed in the
| |
| process. Directory names can be changed but not moved. Global filename
| |
| characters are not allowed in the filename.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location. Refer to "Responding to Errors" on page B-5 and "Extended Error
| |
| Codes" on page B-5 for more information on the codes returned from function
| |
| call 59H.
| |
|
| |
| Network Access Rights: Requires Create access rights.
| |
|
| |
| 57H --
| |
| GET/SET FILE'S DATE AND TIME
| |
|
| |
| PURPOSE
| |
|
| |
| Gets or sets a file's date and time.
| |
|
| |
| EXAMPLE
| |
|
| |
| ; To Get a File's Date and Time
| |
|
| |
| MOV AH,57H ; Function Call -- Get/Set Date and Time
| |
| MOV AL,0 ; Indicate get
| |
| MOV BX,Handle ; Select file
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV FileTime,CX ; Save Time
| |
| MOV FileDate,DX ; Save Date
| |
|
| |
| ; To Set a File's Date and Time
| |
|
| |
| MOV AH,57H ; Function Call -- Get/Set Date and Time
| |
| MOV AL,1 ; Indicate Set
| |
| MOV BX,Handle ; Select file+
| |
| MOV CX,FileTime ; Set Time
| |
| MOV DX,FileDate ; Set Date
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| Handle DW ? ; File Handle (from Open / Create)
| |
| FileTime DW ? ; File Time
| |
| FileDate DW ? ; File Date
| |
|
| |
| COMMENTS
| |
|
| |
| The date and time formats are the same as those for the directory entry
| |
| described in Chapter 5 of this book.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location. Refer to "Responding to Errors" on page B-5 and "Extended Error
| |
| Codes" on page B-5 for more information on the codes returned from function
| |
| call 59H.
| |
|
| |
| 59H --
| |
| GET EXTENDED ERROR
| |
|
| |
| PURPOSE
| |
|
| |
| Returns additional error information, such as the error class, location, and
| |
| recommended action.
| |
|
| |
| EXAMPLE
| |
|
| |
| PUSH DX ; Save Registers
| |
| PUSH SI
| |
| PUSH DI
| |
| PUSH ES
| |
| PUSH DS
| |
| MOV AH,59H ; Function Call -- Get Extended Error
| |
| MOV BX,0 ; Version 0 information
| |
| INT 21H ; Issue request to DOS
| |
| POP DS ; Restore registers
| |
| POP ES
| |
| POP DI
| |
| POP SI
| |
| POP DX
| |
| MOV ExtError,AX ; Save error code
| |
| MOV ErrorClass,BH ; Save error class
| |
| MOV ErrorAction,BL ; Save error action
| |
| MOV ErrorLocation,CH; Save error location
| |
|
| |
|
| |
| ExtError DW ? ; DOS extended error
| |
| ErrorClass DB ? ; Class of error
| |
| ErrorAction DB ? ; Suggested action
| |
| ErrorLocation DB ? ; System area effected
| |
|
| |
| COMMENTS
| |
|
| |
| This function call returns the error class, location, and recommended action,
| |
| in addition to the return code. Use this function call from:
| |
|
| |
| Interrupt 24H error handlers
| |
| Interrupt 21H function calls that return an error in the carry bit
| |
| FCB function calls that return FFH.
| |
|
| |
| On return, the registers contents of DX, SI, DI, ES, CL, and DS are
| |
| destroyed.
| |
|
| |
| ERROR RETURN IN CARRY BIT
| |
|
| |
| For function calls that indicate an error by setting the carry flag, the
| |
| correct method for performing function call 59H is:
| |
|
| |
| Load registers.
| |
| Issue interrupt 21H.
| |
| Continue operation, if carry not set.
| |
| Disregard the error code and issue function call 59H to obtain additional
| |
| information.
| |
| Use the value in BL to determine the suggested action to take.
| |
|
| |
| ERROR STATUS IN AL
| |
|
| |
| For function calls that indicate an error by setting AL to FFH, the correct
| |
| method for performing function call 59H is:
| |
|
| |
| Load registers.
| |
|
| |
| Issue interrupt 21H.
| |
| Continue operation, if error is not reported in AL.
| |
| Disregard the error code and issue function call 59H to obtain additional
| |
| information.
| |
| Use the value in BL to determine the suggested action to take.
| |
|
| |
| 5AH --
| |
| CREATE UNIQUE FILE
| |
|
| |
| PURPOSE
| |
|
| |
| Generates a unique filename, and creates that file in the specified
| |
| directory.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,5AH ; Function Call -- Create a
| |
| ; Unique File
| |
| MOV CX,SEG DirName ; Directory name
| |
| MOV DS,CX
| |
| MOV DX,OFFSET DirName
| |
| MOV CX,Attribute ; File attribute
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV Handle,AX ; Save file handle for following
| |
| ; Operations
| |
|
| |
|
| |
| DirName DB "?? .. ??\",0 ; ASCIIZ name
| |
| DB "????????.???"
| |
| ; example in : "c:\dir\",0
| |
| ; example out: "c:\dir\file",0
| |
| Handle DW ? ; File handle
| |
| Attribute DW ? ; Select file's attribute
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, AH contains 5AH. If no error has occurred, the file is opened in
| |
| compatibility mode with Read/Write access. The read/write pointer is set at
| |
| the first byte of the file and AX contains the file handle and the filename
| |
| is appended to the path specified in DS:DX.
| |
|
| |
| This function call generates a unique name and attempts to create a new file
| |
| in the specified directory. If the file already exists in the directory,
| |
| then another unique name is generated and the process is repeated. Programs
| |
| that need temporary files should use this function call to generate unique
| |
| filenames.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location. Refer to "Responding to Errors" on page B-5 and "Extended Error
| |
|
| |
| Codes" on page B-5 for more information on the codes returned from function
| |
| call 59H.
| |
|
| |
| NOTE: The file created using this function call is not automatically deleted
| |
| at program termination.
| |
|
| |
| Network Access Rights: Requires Create access rights.
| |
|
| |
| 5BH --
| |
| CREATE NEW FILE
| |
|
| |
| PURPOSE
| |
|
| |
| Creates a new file.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,5BH ; Function Call -- Create a New File
| |
| MOV CX,SEG FName ; File Name
| |
| MOV DS,CX
| |
| MOV DX,OFFSET FName
| |
| MOV CX,Attribute
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV Handle,AX ; Save File Handle for following operations
| |
|
| |
|
| |
| FName DB 64 DUP (0) ; ASCIIZ Name
| |
| ; example: "c:\dir\file",0
| |
| Handle DW ? ; File Handle
| |
| Attribute DW ? ; Select File's Attribute
| |
|
| |
| COMMENTS
| |
|
| |
| This function call is the same as function call 3CH (Create), except it will
| |
| fail if the filename already exists. The file is created in compatibility
| |
| mode for reading and writing and the read/write pointer is set at the first
| |
| byte of the file.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location. Refer to "Responding to Errors" on page B-5 and "Extended Error
| |
| Codes" on page B-5 for more information on the codes returned from function
| |
| call 59H.
| |
|
| |
| Network Access Rights: Requires Create access rights.
| |
|
| |
| 5CH --
| |
| LOCK/UNLOCK FILE ACCESS
| |
|
| |
| PURPOSE
| |
|
| |
| Locks or unlocks a single range of bytes in an opened file. This function
| |
| call provides database services that are useful in maintaining database
| |
| integrity in a network environment.
| |
|
| |
| EXAMPLE
| |
|
| |
| ; To Lock a Single Range
| |
|
| |
| MOV AH,5CH ; Function Call --
| |
| ; Access Lock/Unlock File
| |
| MOV AL,0 ; Indicate lock
| |
| MOV BX,Handle ; Select file
| |
| MOV DX,WORD PTR Position+0 ; Set position
| |
| MOV CX,WORD PTR Position+2
| |
| MOV DI,WORD PTR Llength+0 ; Set length
| |
| MOV SI,WORD PTR Llength+2
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
| ; To Unlock a Single Range
| |
|
| |
| MOV AH,5CH ; Function Call --
| |
| ; Lock/Unlock File Access
| |
| MOV AL,1 ; Indicate unlock
| |
| MOV BX,Handle ; Select file
| |
| MOV DX,WORD PTR Position+0 ; Set position
| |
| MOV CX,WORD PTR Position+2
| |
| MOV DI,WORD PTR Llength+0 ; Set length
| |
| MOV SI,WORD PTR Llength+2
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| Handle DW ? ; File Handle
| |
| Position DD ? ; Start of Range
| |
| Llength DD ? ; Length of Range
| |
|
| |
| COMMENTS
| |
|
| |
| The Lock/Unlock function calls should only be used when a file is opened
| |
| using the DenyRead or DenyNone sharing modes. These modes do no local
| |
| buffering of data when accessing files on a network disk.
| |
|
| |
| AL = 00H LOCK
| |
|
| |
| Provides a simple mechanism for excluding other processes' read/write access
| |
| to regions of the file. If another process attempts to read or write in such
| |
| a region, its system call is retried the number of times specified with the
| |
| system retry count set by IOCTL. If, after those retries, no success occurs,
| |
| a general failure error is generated, signaling the condition. The number of
| |
|
| |
| retries, as well as the length of time between retries, can be changed using
| |
| function call 440BH (IOCTL Change Sharing Retry Count).
| |
|
| |
| The recommended action is to issue function call 59H (Get Extended Error) to
| |
| get the error code, in addition to the error class, location, and recommended
| |
| action. The locked regions can be anywhere in the logical file. Locking
| |
| beyond end-of-file is not an error. It is expected that the time in which
| |
| regions are locked will be short. Duplicating the handle duplicates access
| |
| to the locked regions. Access to the locked regions is not duplicated across
| |
| the EXEC system call. Exiting with a file open and having issued locks on
| |
| that file has undefined results.
| |
|
| |
| Programs that may be cancelled using INT 23H (File Size) or INT 24H (Set
| |
| Relative Record Field) should trap these and release the locks before
| |
| exiting. The proper method for using locks is not to rely on being denied
| |
| read or write access, but to attempt to lock the region desired and examining
| |
| the error code.
| |
|
| |
| AL = 01H UNLOCK
| |
|
| |
| Unlock releases the lock issued in the lock system call. The region
| |
| specified must be exactly the same as the region specified in the previous
| |
| lock. Closing a file with locks still in force has undefined results.
| |
| Exiting with a file open and having issued locks on that file has undefined
| |
| results.
| |
|
| |
| Programs that may be aborted using INT 23H (File Size) or INT 24H (Set
| |
| Relative Record Field) should trap these and release the lock before exiting.
| |
| The proper method for using locks is not to rely on being denied read or
| |
| write access, but attempting to lock the region desired and examining the
| |
| error code.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location. Refer to "Responding to Errors" on page B-5 and "Extended Error
| |
| Codes" on page B-5 for more information on the codes returned from function
| |
| call 59H.
| |
|
| |
| 5E00H --
| |
| GET MACHINE NAME
| |
|
| |
| PURPOSE
| |
|
| |
| Returns the character identifier of the local computer.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,SEG CNAME ; Name buffer
| |
| MOV DS,AX
| |
| MOV DX OFFSET CNAME
| |
| MOV AX,5E00H ; Function Call --
| |
| ; Get Machine Name
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV NameFlag,CH ; Save name number indicator
| |
| MOV NameID,CL ; Save NETBIOS name number
| |
|
| |
|
| |
| CName DB "???????????????",0 ; ASCIIZ computer name
| |
| NameFlag DB ? ; 0 = Name is not set
| |
| ; 1 = Name is set
| |
| NameID DB ? ; NETBIOS name number
| |
|
| |
| COMMENTS
| |
|
| |
| Get Machine Name returns the text of the current computer name to the caller.
| |
| The computer name is a 15-character byte string padded with spaces and
| |
| followed by a 00H byte. If the computer name was never set, register CH is
| |
| returned with 00H and the value in the CL register is invalid. The IBM PC
| |
| Local Area Network program must be loaded for the function call to execute
| |
| properly.
| |
|
| |
| 5E02H --
| |
| SET PRINTER SETUP
| |
|
| |
| PURPOSE
| |
|
| |
| Specifies an initial string for printer files.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,5E02H ; Function Call --
| |
| ; Set Printer Setup
| |
| MOV BX,Index ; Redirection List Index
| |
| MOV CX,size ; String size
| |
| MOV SI,SEG String ; String Buffer
| |
| MOV DS,SI
| |
| MOV SI,OFFSET String
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| Index DW ? ; Redirection List Index
| |
| Size DW N ; String size (Maximum 64)
| |
| String DB N DUP(?) ; Printer Setup String
| |
|
| |
| COMMENTS
| |
|
| |
| The string specified is put in front of all files destined for a particular
| |
| network printer. Set Printer Setup allows multiple users of a single printer
| |
| to specify their own mode of operation for the printer. BX is set to the
| |
| same index that is used in function call 5F02H (Get Redirection List Entry).
| |
| An error code is returned if print redirection is paused or if the IBM PC
| |
| Local Area Network program is not loaded.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location. Refer to "Responding to Errors" on page B-5 and "Extended Error
| |
| Codes" on page B-5 for more information on the codes returned from function
| |
| call 59H.
| |
|
| |
| IMPORTANT: The redirection index value may change if function call 5F03H
| |
| (Redirect Device) or function call 5F04H (Cancel Redirection) is issued
| |
| between the time the redirection list is scanned and the function call 5E02H
| |
| (Set Printer Setup) is issued. Therefore, we recommend that you issue Set
| |
| Printer Setup immediately after you issue "Get Redirection List ."
| |
|
| |
| 5E03H --
| |
| GET PRINTER SETUP
| |
|
| |
| PURPOSE
| |
|
| |
| Returns the printer setup string for printer files.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,5E03H ; Function Call --
| |
| ; Get Printer Setup
| |
| MOV BX,Index ; Redirection List Index
| |
| MOV CX,SEG String ; String Buffer
| |
| MOV ES,CX
| |
| MOV DI,OFFSET String
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV Ssize, CX ; Save String size
| |
|
| |
|
| |
| Index DW ? ; Redirection List Index
| |
| Ssize DW ? ; String size
| |
| String DB 64 DUP(?) ; Printer Setup String
| |
|
| |
| COMMENTS
| |
|
| |
| This function call returns the printer setup string which was specified using
| |
| the function call 5E02H (Set Printer Setup). The setup string is attached to
| |
| all files destined for a particular printer. The value in BX is set to the
| |
| same index issued in function call 5F02H (Get Redirection List). Error code
| |
| 1 (invalid function number) is returned if the IBM PC Local Area Network is
| |
| not loaded.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location. Refer to "Responding to Errors" on page B-5 and "Extended Error
| |
| Codes" on page B-5 for more information on the codes returned from function
| |
| call 59H.
| |
|
| |
| IMPORTANT: The redirection index value may change if function call 5F03H
| |
| (Redirect Device) or function call 5F04H (Cancel Redirection) is issued
| |
| between the time the redirection list is scanned and the function call 5E03H
| |
| (Get Printer Setup) is issued. Therefore, we recommend that you issue "Get
| |
| Printer Setup" immediately after you issue "Get Redirection List."
| |
|
| |
| 5F02H --
| |
| GET REDIRECTION LIST ENTRY
| |
|
| |
| PURPOSE
| |
|
| |
| Returns nonlocal network assignments.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV BX,0 ; Start at beginning of list
| |
| Get_Loop: ; Get next entry
| |
| MOV Index,BX ; Redirection list index
| |
| MOV AX,5F02H ; Function Call --
| |
| ; Get redirection list entry
| |
| MOV SI,SEG device ; "PRN" is possible
| |
| MOV DS,SI
| |
| MOV SI,OFFSET device ; DS:SI points to local name
| |
| MOV DI,SEG info
| |
| MOV ES,DI
| |
| MOV DI,OFFSET inf ; ES:DI points to buffer address of netwo
| |
| PUSH BX
| |
| PUSH DX ; Save registers
| |
| PUSH BP
| |
| INT 21H ; Issue request to DOS
| |
| POP BP ; Restore registers
| |
| POP DX
| |
| JC CheckEnd ; Error code in AX
| |
| MOV Status,BH ; Save status
| |
| MOV Type,BL ; Save type
| |
| MOV UserParm,CX ; Save user parmameter
| |
| POP BX
| |
| INC BX ; Set to next entry
| |
| JMP Get_Loop
| |
|
| |
| CheckEnd:
| |
| POP BX ; Balance state
| |
| CMP AX,18 ; End of list?
| |
| JNE Error ; No!
| |
|
| |
|
| |
| Index DW ? ; Redirection list index (0 based)
| |
| Device DB 128 DUP(?) ; ASCIIZ device name
| |
| ; example: "LPT1",0
| |
| ; "A:",0
| |
| Status DB ? ; Device status
| |
| ; Bit 0=0 : Device is OK
| |
| ; Bit 0=1 : Device in Error
| |
| ; Bit 7-1 reserved
| |
| UserParm DW ? ; User parameter
| |
| Type DB ? ; Device type
| |
| ; 3 = NET USE device
| |
| ; 4 = NET USE drive
| |
| Info DB 128 DUP(?) ; NET USE network path
| |
| ; example: "\\MYNODE\CDRIVE",0
| |
|
| |
| COMMENTS
| |
|
| |
| The Get Redirection List Entry function call returns the list of network
| |
| redirections that were created through function call 5F03H (Redirect Device).
| |
| Each call returns one redirection, so BX should be increased by one each time
| |
| to step through the list. The contents of the list may change between calls.
| |
| The end-of-list is detected by error code 18 (no more files). Error code 1
| |
| (invalid function number) is returned if the IBM PC Local Area Network
| |
| program is not loaded.
| |
|
| |
| If either disk or print redirection is paused, the function is not effected.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location. Refer to "Responding to Errors" on page B-5 and "Extended Error
| |
| Codes" on page B-5 for more information on the codes returned from function
| |
| call 59H.
| |
|
| |
| 5F03H --
| |
| REDIRECT DEVICE
| |
|
| |
| PURPOSE
| |
|
| |
| Causes a Redirector/Server connection to be made.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,5F03H ; Function Call --
| |
| ; Redirect Device
| |
| MOV SI,SEG Device ; Device Buffer
| |
| MOV DS,SI
| |
| MOV SI,OFFSET Device
| |
| MOV DI,SEG Net Path info ; Information Buffer
| |
| MOV ES,DI
| |
| MOV DI,OFFSET Net Path
| |
| MOV BL,Type ; Set Type
| |
| MOV CX,UserParm ; Set User Parameter
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| Device DB "....",0 ; ASCIIZ Device Name
| |
| ; example: "LPT1",0
| |
| ; "A:",0
| |
| UserParm DW ? ; User Parameter
| |
| Type DB ? ; Device Type
| |
| ; 3 = NET USE Device
| |
| ; 4 = NET USE Drive
| |
| Net Path DB 128 DUP(0)
| |
|
| |
| COMMENTS
| |
|
| |
| This call defines the current directories for the network and defines
| |
| redirection of network printers.
| |
|
| |
| If BL = 03, the source specifies a printer, the destination specifies a
| |
| network path, and the CX register has a word that DOS 4.00 maintains for
| |
| the programmer. For compatibility with the IBM PC Local Area Network
| |
| program, CX should be set to 0. Values other than 0 are reserved for the
| |
| IBM PC Local Area Network program. This word may be retrieved through
| |
| function call 5F02H (Get Redirection List). All output destined for the
| |
| specified printer is buffered and sent to the remote printer spool for
| |
| that device. The printers are redirected at the INT 17H level.
| |
|
| |
| The source string must be PRN , LPT1, LPT2, or LPT3 each ended with a
| |
| 00H. The destination string must point to a network name string of the
| |
| following form:
| |
|
| |
| [\\computername\¤shortname|printdevice‡]
| |
|
| |
| The destination string must be ended with a 00H.
| |
|
| |
| The ASCIIZ password (0 to 8 characters) for access to the remote device
| |
| should immediately follow the network string. The password must end with
| |
| a 00H. A null (0 length) password is considered to be no password.
| |
|
| |
| If BL = 4, the source specifies a drive letter and colon ending with 00H,
| |
| the destination specifies a network path ending with 00H, and the CX
| |
| register has a word that DOS maintains for the programmer. For
| |
| compatibility with the IBM PC Local Area Network program, CX should be
| |
| set to 00H. Values other than 00H are reserved for the IBM PC Local Area
| |
| Network program. The value may be retrieved through function call 5F02H
| |
| (Get Redirection List). If the source was a drive letter, the
| |
| association is made between the drive letter and the network path. All
| |
| subsequent references to the drive letter are translated to references to
| |
| the network path. If the source is an empty string, the system attempts
| |
| to grant access to the destination with the specified password without
| |
| redirecting any device.
| |
|
| |
| The ASCIIZ password for access to the remote path should immediately
| |
| follow the network string. A null (0 length) password ended with 00H is
| |
| considered to be no password.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H for additional
| |
| information about the error class, suggested action, and location. Refer
| |
| to "Responding to Errors" on page B-5 and "Extended Error Codes" on
| |
| page B-5 for more information on the codes returned from function call
| |
| 59H (Get Extended Error) .
| |
|
| |
| NOTES:
| |
|
| |
| 1. Devices redirected through this function call are not displayed by the
| |
| NET USE command.
| |
|
| |
| 2. An error is returned if you try to redirect a drive while disk
| |
| redirection is paused, or if you try to redirect a printer while print
| |
| redirection is paused.
| |
|
| |
| 5F04H --
| |
| CANCEL REDIRECTION
| |
|
| |
| PURPOSE
| |
|
| |
| Cancels a previous redirection.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AX,5F04H ; Function Call --
| |
| ; Cancel redirection
| |
| MOV SI,SEG Device ; Device buffer
| |
| MOV DS,SI
| |
| MOV SI,OFFSET Device
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| Device DB "....",0 ; ASCIIZ Device Name
| |
| ; example: "LPT1",0
| |
| ; "A:",0
| |
| ; "\\Computer\Path",0
| |
|
| |
| COMMENTS
| |
|
| |
| The redirection created by the Redirect Device function call (5F03H) is
| |
| removed through the Cancel Redirection call. If the buffer points to a drive
| |
| letter and the drive is associated with a network name, the association is
| |
| ended and the drive is restored to its physical meaning. If the buffer
| |
| points to PRN, LPT1, LPT2, or LPT3, and the device has an association with a
| |
| network device, the association is terminated and the device is restored to
| |
| its physical meaning. If the buffer points to a network path ending with 00H
| |
| and a password ending with 00H, the association between the local machine and
| |
| the network directory is terminated.
| |
|
| |
| An error is returned if you try to cancel a redirected file device while disk
| |
| redirection is paused, or if you try to cancel a redirected printer while
| |
| print redirection is paused. Error code 1 (invalid function number) is
| |
| returned if the IBM PC Local Area Network program is not loaded.
| |
|
| |
| Error codes are returned in AX. Issue function call 59H (Get Extended Error)
| |
| for additional information about the error class, suggested action, and
| |
| location. Refer to "Responding to Errors" on page B-5 and "Extended Error
| |
| Codes" on page B-5 for more information on the codes returned from function
| |
| call 59H.
| |
|
| |
| 62H --
| |
| GET PROGRAM SEGMENT PREFIX ADDRESS
| |
|
| |
| PURPOSE
| |
|
| |
| Returns the program prefix address.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,62H ; Function Call --
| |
| ; Get Program Segment Prefix Address
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV PSPSeg,BX ; Save PSP address
| |
|
| |
|
| |
| PSPSeg DW ? ; Segment address of my PSP
| |
|
| |
| COMMENTS
| |
|
| |
| The internal PSP address for the currently executing process is returned in
| |
| BX.
| |
|
| |
| 65H --
| |
| GET EXTENDED COUNTRY INFORMATION
| |
|
| |
| PURPOSE
| |
|
| |
| Returns extended country information.
| |
|
| |
| EXAMPLE
| |
|
| |
| ; To get information
| |
|
| |
| MOV AH,65H ; Function Call --
| |
| ; Get extended country information
| |
| MOV AL,InfoID ; Data/function requested
| |
| ; (1, 2, 4, 6 or 7).
| |
| MOV BX,CodePage ; Set desired code page
| |
| ; (-1=current, Set by function call 6602H).
| |
| MOV CX,SizeBuffer ; Maximum data to return
| |
| ; (must be >= 5)
| |
| MOV DX,CountryID ; Set desired Country ID
| |
| ; (-1=current, set by function call 38H).
| |
| MOV DI,SEG Buffer ; Information return buffer
| |
| MOV DS,DI
| |
| MOV DI,OFFSET Buffer
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| Buffer LABEL BYTE
| |
| ; Format depends on AL value
| |
| ; AL=1 : Extended Country Information
| |
|
| |
| SizeBuffer DW ? ; Size of data block to return
| |
| InfoID DB ? ; Type of info to get
| |
| CIinfoSize DW ? ; amount of data that follows
| |
| ; (limited by CX input)
| |
| CountryID DW ? ; Selected CountryID
| |
| CodePage DW ? ; Selected Code Page
| |
| ; See function call 38H for the format of the remainder of this buffer
| |
|
| |
|
| |
| ; AL=2 : Upper Case Table
| |
| DB 2 ; Indicates Upper Case Table
| |
| UpperCase@ DD ? ; Address of Upper Case Table
| |
|
| |
| ; AL=4 : File Upper Case Table
| |
| DB 4 ; Indicates File Upper Case Table
| |
| UpperCase@ DD ? ; Address of File Upper Case Table
| |
|
| |
| ; AL=6 : Collating Table
| |
| DB 6 ; Indicates Collate Table
| |
| Collate@ DD ? ; Address of Collate Table
| |
|
| |
| ; AL=7 : DBCS Vector Table
| |
| DB 7 ; Indicates DBCS Vector Table
| |
| DBCS@ DD ? ; Address of DBCS Vector Table
| |
|
| |
| COMMENTS
| |
|
| |
| On entry, DX contains the ID of the country for which the extended
| |
| information is needed. AL contains the ID value for the country.
| |
|
| |
| If the country code and code page do not match, or if either one or both
| |
| are invalid, an error code of 2 (file not found) is returned in AX.
| |
| The size requested in CX must be 5 or greater. If it is less than 5, an
| |
| error code of 1 is returned in AX.
| |
| If the amount of information returned is greater than the size requested
| |
| in CX, it is ended and no error is returned in AX.
| |
|
| |
| NOTE: For further information on the country information, see function call
| |
| 38H (Get or Set Country Dependent Information).
| |
|
| |
| The NLSFUNC DOS extension must be installed to get information for
| |
| countries other than the Current Country.
| |
|
| |
| The uppercase table and the filename uppercase tables are 130 bytes long,
| |
| consisting of a length field (2 bytes), followed by 128 uppercase values for
| |
| the upper 128 ASCII characters. They have the following layout:
| |
|
| |
| Tsize DW 128 ; Table Size
| |
| Table DB 128 DUP(?) ; Upper case versions of 80H to FFH
| |
|
| |
| The following formula can be used to determine the address of an uppercase
| |
| equivalent for a lowercase character (ASCII in) in the uppercase table or the
| |
| filename uppercase table.
| |
|
| |
| EXAMPLE
| |
|
| |
| ASCII in -(256-table len)+table start= address of ASCII out
| |
|
| |
| WHERE
| |
|
| |
| ASCII in = character to be generated
| |
|
| |
| table len = length of list of uppercase
| |
| values (2 bytes)
| |
|
| |
| table start = starting address of uppercase
| |
| table (4 bytes)
| |
|
| |
| ASCII out = uppercase value for ASCII in
| |
|
| |
| If the value of ASCII in is equal to or greater than (256-table len), there
| |
| is an uppercase equivalent for ASCII in in the table. If it is lower than
| |
| (256-table len), no uppercase equivalent exists in the table.
| |
|
| |
| The collate table is 258 bytes long, consisting of a length field (2 bytes)
| |
| followed by 256 ASCII values, in the appropriate order. It has the following
| |
| layout:
| |
|
| |
| Tsize DW 256 ; Table Size
| |
| Table DB 256 DUP(?) ; Sort Weights for 00H to FFH
| |
|
| |
| The DBCS vector is variable in length, consisting of a length field (two
| |
| bytes) followed by one or more pairs of bytes. It has the following layout:
| |
|
| |
| Tsize DW Nx2 ;List size
| |
| 1 DB Start,end ;DBCS vector 1
| |
| 2 DB Start,end ;DBCS vector 2
| |
| :
| |
| N DB Start,end ;DBCS vector n
| |
| DB 0,0 ;End marker
| |
|
| |
| 66H --
| |
| GET/SET GLOBAL CODE PAGE
| |
|
| |
| PURPOSE
| |
|
| |
| This function gets or sets the code page for the current country.
| |
|
| |
| MOV AX,6601H ; Function Call --
| |
| ; Get Global Code Page
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV GlobalCP,BX ; Save Global Code Page
| |
| MOV SystemCP,DX ; Save DOS System Code Page
| |
|
| |
| or
| |
|
| |
| MOV AX,6602H ; Function Call --
| |
| ; Set Global Code Page
| |
| MOV BX,GlobalCP ; New Global Code Page
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| GlobalCP DW ? ; Current Code Page of DOS Country Informati
| |
| SystemCP DW ? ; Code Page of DOS messages
| |
| ; Often the default Code Page for the
| |
| ; current country
| |
|
| |
| COMMENTS
| |
|
| |
| DOS 4.00 moves the new code page data from the COUNTRY.SYS file to a resident
| |
| country buffer area. DOS 4.00 uses the new code page to perform a Select to
| |
| all attached devices that are set up for code page switching, (that is, have
| |
| a code page switching device driver specified in CONFIG.SYS). If any device
| |
| fails to be selected, an error code of 65 is returned in AX. The code page
| |
| must be recognizable by the current country, and DOS 4.00 must be able to
| |
| open and read from the country information file. Otherwise, the carry flag
| |
| will be set on return and AX will contain 02 (file not found).
| |
|
| |
| NOTE: NLSFUNC must be installed to use this function call, and all the
| |
| devices must be prepared in order for the Select function to be
| |
| successful.
| |
|
| |
| 67H --
| |
| SET HANDLE COUNT
| |
|
| |
| PURPOSE
| |
|
| |
| Permits more than 20 open files per process.
| |
|
| |
| EXAMPLE
| |
|
| |
| EntryPoint:
| |
| MOV AH,62H ; Function Call --
| |
| ; Get PSP Address
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV ES,BX ; Set Segment
| |
| MOV AH,4AH ; Function Call --
| |
| ; Set Memory Block Size
| |
| MOV BX,paragraphs ; Set Size
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
| MOV AH,67H ; Function Call - Set Handle Count
| |
| MOV BX,NewHandles ; Set new handle count
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| NewHandles DW ? ; Number of Handles need
| |
| ; by this DOS 4.00 proce
| |
| ListSize EQU (Endofprogram - EntryPoint) ; Number of bytes
| |
| Paragraphs EQU (ListSize / 10H) ; Number of paragraphs
| |
| End_of_program LABEL BYTE ; Last used position for
| |
| ; this program
| |
|
| |
| COMMENTS
| |
|
| |
| The maximum number of file handles allowed for this interrupt is 64KB. If
| |
| the the specified number of allowable handles is less than the current number
| |
| allowed, the specified number will become current only after all the handles
| |
| above the specified number have been closed. If the specified number is less
| |
| than 20, the number is assumed to be 20. Data base applications can use this
| |
| function to reduce the need to swap handles.
| |
|
| |
| You must release memory for DOS 4.00 to contain the extended handle list.
| |
| You can do this by using the SET BLOCK (4AH) function call.
| |
|
| |
| 68H --
| |
| COMMIT FILE
| |
|
| |
| PURPOSE
| |
|
| |
| Causes all buffered data for a file to be written to the device. This
| |
| function can be used instead of a close-open sequence.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,68H ; Function Call -- Commit File
| |
| MOV BX,Handle ; Select file
| |
| INT 21H ; Issue request to DOS
| |
| JC Error ; Error code in AX
| |
|
| |
|
| |
| Handle DW ? ; Handle from previous Open or Create
| |
|
| |
| COMMENTS
| |
|
| |
| Commit File provides a faster and more secure method of committing data in
| |
| multi-user environments such as the IBM PC Local Area Network.
| |
|
| |
| 6CH --
| |
| EXTENDED OPEN/CREATE
| |
|
| |
| PURPOSE
| |
|
| |
| Optionally opens and creates a file.
| |
|
| |
| EXAMPLE
| |
|
| |
| MOV AH,6CH ; Extended open
| |
| MOV AL,0 ; Reserved
| |
| MOV BX,MODE ; Open mode
| |
| ; Format : 0WF00000ISSS0AAA
| |
| ; AAA=Access code 0=Read
| |
| ; 1=Write
| |
| ; 2=Read/Write
| |
| ; SSS=Sharing mode 0=Compatibility
| |
| ; 1=DenyRead/Write
| |
| ; 2=DenyWrite
| |
| ; 3=DenyRead
| |
| ; 4=DenyNone
| |
|
| |
| ; I 0=Pass handle to chile, 1=No inherit
| |
| ; F 0=INT 24H, 1=Return error
| |
| ; on this open and any I/O to this handle
| |
| ; W 0=No commit, 1=Auto-Commit on write
| |
| MOV CX,ATTR ; Create attribute (ignored if open)
| |
| MOV DX,FLAG ; Function control, Format=0000000NNNNEEEE
| |
| ; NNNN=Does not exist action
| |
| ; 0=Fail, 1=Create
| |
| ; EEEE=Exists action
| |
| ; 0=Fail, 1=open, 2=Replace/Open
| |
|
| |
| MOV SI,SEG file name ; Name to open or create
| |
| MOV DS,SI
| |
| MOV SI,OFFSET file name
| |
| INT 21H
| |
| JC ERROR
| |
| ; AX=Handle
| |
| ; CX=Action taken code
| |
| ; 1=File opened
| |
| ; 2=File created/opened
| |
| ; 3=File replaced/opened
| |
|
| |
| ;----
| |
| Mode DW ? ; Open mode bit
| |
| ; Definitions
| |
| Attr DW ? ; File attributes
| |
| Flag DW ? ; Function definition
| |
| File name 64 DUP (0)
| |
|
| |
| COMMENTS
| |
|
| |
| Function 6CH combines the functions currently available with OPEN, CREATE and
| |
| a CREATE NEW.
| |
|
| |
| If F is 1, the critical error handler (Interrupt 24) is disabled for the
| |
| handle returned by Extended Open. Any I/O issued to this handle will never
| |
| generate the critical error but only the extended error.
| |
|
| |
| If F is 0, no actions are taken.
| |
|
| |
| If W is 1, any disk write using the handle returned by Extended Open will
| |
| accompany with a commit call (see Interrupt 21H (AL=68H)).
| |
|
| |
| If W is 0, no actions are taken.
| |
| </PRE>
| |
| | |
| [[Category:DOS Books]] | |