|
|
(5 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 9==
| |
| <PRE>
| |
| CHAPTER 9. CONVERTING FILE FORMATS 8
| |
| The EXE2BIN.EXE Utility 13
| |
| Entering Input to EXE2BIN 34
| |
| Two Types of Conversion 61
| |
| Device Drivers 66
| |
| Standard .COM File 100
| |
|
| |
| 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== | | ==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 10. DEBUGGING A PROGRAM 32
| | programmers develop an application program: |
| The DEBUG Utility 37
| | *DEBUG.COM - A utility to isolate and determine errors in executable programs. |
| Starting the DEBUG.COM Program 46
| | *EXE2BIN.EXE - A utility to convert executable file formats (.EXE) to .COM formats to make them more compact and, therefore, load more quickly. |
| Entering Commands at the DEBUG Prompt 67
| | *LIB.EXE - A utility that allows the programmer to build and edit object libraries. |
| DEBUG Command Summary 103
| | *LINK.EXE - A utility to translate object code to executable code. |
| The DEBUG Work Space 181
| | *VDISK.ASM - A fully documented programming example of a device driver. However, this example does not reflect the current level of VDISK.SYS. |
| 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
| |
|
| |
| 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== | | ==Links== |
| <PRE>
| | *[https://archive.org/download/bitsavers_ibmpcdos15lReferenceJul88_10507385/15F0256_DOS_4.0_Technical_Reference_Jul88.pdf PDF] |
| CHAPTER 11. WRITING AN INSTALLABLE DEVICE DRIVER 26
| | *{{L-IBMAnnUS|ZP88-0364}} 1988-07-20 - Disk Operating System Version 4.00 |
| 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
| | [[Category:DOS Documentation]] |
|
| |
| 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]] | |