Jump to content

Virtual Device Driver Reference for OS/2: Difference between revisions

From EDM2
← Older edit
Ak120 (talk | contribs)
35,819 edits
 
(18 intermediate revisions by 3 users not shown)
Line 1: Line 1:
By [[IBM]]
{{IBM-Reprint}}
{{VDDRef}}
==EDM/2 preamble==
This is the ''Virtual Device Driver Reference for OS/2'' as last published by IBM in 1995. It is republished here with explicit permission from the company (Copyright Permission #21953) and you should keep in mind that it is an intellectual property of International Business Machines Corp. that cannot be changed or reused without their permission and is not governed by the [[Attribution-Share Alike 3.0]] licence like the rest of the EDM/2 Wiki.


The content of the documentation is unchanged apart from the following:
* The original document was an INF file split into thousands of different small sections, these have been consolidated into chapters, and restructured to fit [[HTML]] formatting, mimicking the original [[GML]] format as much as possible.
* Sales, technical help, download and contact information has been removed. The VDDR/2 and the related SDK's are no longer for sale, nor is support available from IBM. Some of the INF viewer related help has been removed as well as it is superfluous after the format change and might be misleading, and the Glossary and Notices section was merged with other DDK/SDK glossary sections as they are all identical.
* Miniscule changes have been made to the text, spelling errors, formatting errors and possible copy and paste errors have been fixed and/or noted.


=About This Book =
Outside of formatting changes, adding Wikilinks and graphic improvements, the document shall be left as it is. It should be noted that the some of the driver models and data formats described in the documentation are have been replaced or extended by both IBM and third parties, but that does not mean that this document should be changed, but it is acceptable that a link is created to an internal or external article that explains the newer models and formats.


The ''OS/2 Virtual Device Driver Reference''defines what a virtual device driver is, how it operates, and when to use one. In addition, a description of the types of virtual device drivers, their interfaces, and the available kernel services is provided. System and application programmers can use the information found in this book to write their own virtual device drivers and subsystems.
==About This Book==
The ''OS/2 Virtual Device Driver Reference'' defines what a virtual device driver is, how it operates, and when to use one. In addition, a description of the types of virtual device drivers, their interfaces, and the available kernel services is provided. System and application programmers can use the information found in this book to write their own virtual device drivers and subsystems.


Knowledge of a programming language (such as C or assembler) that is used for writing OS/2 applications is necessary, and the programmer must be familiar with the workings of the OS/2 operating system.
Knowledge of a programming language (such as C or assembler) that is used for writing OS/2 applications is necessary, and the programmer must be familiar with the workings of the OS/2 operating system.


 
===How This Book is Organized===
 
==How This Book is Organized ==
 
This book consists of three parts:
This book consists of three parts:


''Part 1. Overview''
''Part 1. Overview''
 
;[[#Introduction|Introduction]]:This chapter contains a general description of the three types of OS/2 device drivers, and an overview of the virtual device driver mechanism and kernel services.
[[00005.htm|Introduction]]This chapter contains a general description of the three types of OS/2 device drivers, and an overview of the virtual device driver mechanism and kernel services.
;[[Virtual Device Driver Architecture and Operations]]:This chapter contains a description of virtual device driver architecture, operations, and communication between device drivers.
 
[[00011.htm|Virtual Device Driver Architecture and Operations]]This chapter contains a description of virtual device driver architecture, operations, and communication between device drivers.
 
''Part 2. Virtual Device Drivers''
''Part 2. Virtual Device Drivers''
 
;[[Base Virtual Device Drivers]]:This chapter contains a description of each base virtual device driver shipped with OS/2.
[[00043.htm|Base Virtual Device Drivers]]This chapter contains a description of each base virtual device driver shipped with OS/2.
;[[Installable Virtual Device Drivers]]:This chapter contains a description of each installable virtual virtual device driver shipped with OS/2.
 
;[[Virtual Mouse Device Driver]]:This chapter describes the virtual mouse device driver (VMOUSE), which is responsible for all mouse support in multiple DOS sessions.
[[00088.htm|Installable Virtual Device Drivers]]This chapter contains a description of each installable virtual virtual device driver shipped with OS/2.
 
[[00105.htm|Virtual Mouse Device Driver]]This chapter describes the virtual mouse device driver (VMOUSE), which is responsible for all mouse support in multiple DOS sessions.
 
''Part 3. Reference Material''
''Part 3. Reference Material''
 
;[[C Language Virtual DevHlp Services]]:This chapter contains full C language descriptions of the kernel functions available to virtual device drivers.
[[00129.htm|C Language Virtual DevHlp Services]]This chapter contains full C language descriptions of the kernel functions available to virtual device drivers.
 
''Appendixes''
''Appendixes''
;[[#OS/2 Version Compatibility Considerations|OS/2 Version Compatibility Considerations]]:This table describes information added to or changed since the availability of OS/2 Warp, Version 3 in terms of version compatibility.
;[[Assembler Language Syntax]]:This appendix contains assembler language versions of the kernel functions covered in Chapter 6.
;[[IBM SDK/DDK Notices|Notices]]:This appendix contains legal notices and lists the trademarks of the IBM Corporation and trademarks of other companies.


[[01167.htm|OS/2 Version Compatibility Considerations]]This table describes information added to or changed since the availability of OS/2 Warp, Version 3 in terms of version compatibility.
A [[IBM SDK/DDK Glossary|glossary]] and an index are included at the back of this book.
 
[[01168.htm|Assembler Language Syntax]]This appendix contains assembler language versions of the kernel functions covered in Chapter 6.
 
[[02205.htm|Notices]]This appendix contains legal notices and lists the trademarks of the IBM Corporation and trademarks of other companies.
 
A glossary and an index are included at the back of this book.
 


 
==Introduction==
 
Virtual device drivers are used by the OS/2* operating system to act as virtual devices for DOS applications executing in a DOS session. These device drivers provide ''virtual hardware'' support for DOS and DOS applications.
 
==Assistance ==
 
Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system ( BBS) known as the "DUDE." You are encouraged to use the DUDE to obtain support by sending in your questions and reviewing the question and answer database which can be downloaded for off-line review.
 
To access the DUDE, dial 512-838-9717 (using a modem) to register and access the support system. For voice support in the United States, call 512 -838-9493.
 
Additional assistance is available through the IBM Solution Developer Program. For membership information:
 
Internet: ibmsdp@vnet.ibm.com
 
US/Canada: 800-627-8363
 
International: 770-835-9902
 
International Fax: 770-835-9444
 
 
 
== Ordering Information ==
 
For an illustration of OS/2 Technical Publications and other related product documents, see the figure labeled "OS/2 Technical Publications". The documents represented in this illustration are available only in English.
 
In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, this CD-ROM also includes the following DDK reference books in online format.
 
*The Physical Device Driver Reference <br />
*The Storage Device Driver Reference <br />
*The Input/Output Device Driver Reference <br />
*The Pen for OS/2 Device Driver Reference <br />
*The Virtual Device Driver Reference <br />
*The Presentation Device Driver Reference <br />
*The Display Device Driver Reference <br />
*The Printer Device Driver Reference <br />
*The Graphics Adapter Device Driver Reference <br />
*The MMPM/2 Device Driver Reference (Multimedia) <br />
To order the DDK call:
 
<pre class="western">/----------------------------------------------------------------\
|U.S.A.:            |1-800-633-8266      |                    |
|--------------------+---------------------+---------------------|
|Canada:            |1-800-561-5293      |                    |
|--------------------+---------------------+---------------------|
|When calling from  |* English            |(+45) 48101500      |
|Europe, the Middle  |* French            |(+45) 48101200      |
|East, or Africa, the|* Italian            |(+45) 48101600      |
|number depends on  |* German            |(+45) 48101000      |
|the language you use|* Spanish            |(+45) 48101100      |
|to place the order: |* Dutch              |(+45) 48101400      |
|                    |* Danish            |(+45) 48101300      |
|                    |* Finish            |(+45) 48101650      |
|                    |* Swedish            |(+45) 48101150      |
|                    |* Norwegian          |(+45) 48101250      |
|                    |* FAX                |(+45) 48142207      |
|--------------------+---------------------+---------------------|
|When ordering from  |* Bolivia            |    02-35 1840      |
|Latin America or    |* Columbia          |  01-257-0111      |
|South America, the  |* Dominican Republic |      566-5161      |
|number depends on  |* El Salvador        |    02-98 5011      |
|the country from    |* Honduras          |      32-2319      |
|which you are      |* Paraguay          |  021-444 094      |
|calling:            |* Urugruay          |    02-923 617      |
|                    |* Chile              |  02-633-4400      |
|                    |* Costa Rica        |      223-6222      |
|                    |* Ecuador            |    02-56 5100      |
|                    |* Guatemala          |    02-31 5859      |
|                    |* Panama            |    02-639 977      |
|                    |* Peru              |  014-36 6345      |
|                    |* Venezuela          |  02-908-8901      |
|                    |* Argentina          |  01-313-0014      |
|--------------------+---------------------+---------------------|
|To order from Asia/ |* All except Japan  |(61) 2-354-7684      |
|Pacific:            |* Japan              |(81) 3-3495-2045(Fax)|
|                    |                    |Fax request to:      |
|                    |                    |DAP-J, IBM Japan    |
|--------------------+---------------------+---------------------|
|To order from SE    |(021) 800-6120(Voice)|                    |
|Brazil:            |(021) 800-6936(Fax)  |                    |
|--------------------+---------------------+---------------------|
|To order from      |* Mexico City        |627-2444            |
|Mexico:            |* Country            |91-800-00639        |
\----------------------------------------------------------------/</pre>
 
 
 
 
= What's New =
 
Following is a list of the changes made to the ''OS/2 Virtual Device Driver Reference''(Fourth Edition) since it was published in April 1995.
 
*[[00102.htm|Virtual Advanced OS/2 Joystick Device Driver]]has been added to [[00088.htm|Installable Virtual Device Drivers]]
 
Refer to [[01167.htm|OS/2 Version Compatibility Considerations]]for a table listing compatibility information about new information in this book.
 
 
 
 
 
= Introduction =
 
Virtual device drivers are used by the OS/2* operating system to act as virtual devices for DOS applications executing in a DOS session. These device drivers provide ''virtual hardware''support for DOS and DOS applications.


The virtual device drivers shipped with OS/2 will virtualize most of the standard devices, including:
The virtual device drivers shipped with OS/2 will virtualize most of the standard devices, including:
 
*Asynchronous Communication (RS-232C)
*Asynchronous Communication (RS-232C) <br />*DMA (Direct Memory Access) <br />*Fixed Disk and Diskette <br />*Keyboard <br />*Mouse <br />*Parallel Port Printer <br />*PIC (Programmable Interrupt Controller) <br />*Timer <br />*Video
*DMA (Direct Memory Access)
 
*Fixed Disk and Diskette
*Keyboard
*Mouse
*Parallel Port Printer
*PIC (Programmable Interrupt Controller)
*Timer
*Video
This book provides an overview of the virtual device driver mechanism and the available kernel services.
This book provides an overview of the virtual device driver mechanism and the available kernel services.


==Types of OS/2 Device Drivers ==
==Types of OS/2 Device Drivers ==
Three types of device drivers are used in the OS/2 operating system:
Three types of device drivers are used in the OS/2 operating system:
*Virtual device drivers
*Physical device drivers
*Presentation drivers


*Virtual device drivers <br />*Physical device drivers <br />*Presentation drivers
===Virtual Device Drivers===
 
 
 
 
 
=== Virtual Device Drivers ===
 
The virtual device driver is an installable module, responsible for virtualizing a particular piece of hardware and associated ROM BIOS in the manner expected by a DOS application. This device driver achieves virtualization by emulating I/O port and device memory operations. Virtual device drivers are 32-bit device drivers, operating at Ring 0, the most privileged level of the operating system. To achieve a certain level of hardware independence, a virtual device driver usually communicates with a physical device driver in order to interact with hardware.
The virtual device driver is an installable module, responsible for virtualizing a particular piece of hardware and associated ROM BIOS in the manner expected by a DOS application. This device driver achieves virtualization by emulating I/O port and device memory operations. Virtual device drivers are 32-bit device drivers, operating at Ring 0, the most privileged level of the operating system. To achieve a certain level of hardware independence, a virtual device driver usually communicates with a physical device driver in order to interact with hardware.


 
===Physical Device Drivers===
 
Standard I/O devices are supported by base physical device drivers that are part of the OS/2 operating system. Additional or replacement physical device drivers can be loaded to extend the control provided by the base device drivers, or to support nonstandard I/O devices. Typical examples of these loadable device drivers are ANSI.SYS and ANSI.DLL, which are loaded by "DEVICE=" statements in the CONFIG.SYS file, and provide additional functions on the interfaces to the screen and keyboard. Physical device drivers are initialized at Ring 3 and operate at Ring 0.
 
 
=== Physical Device Drivers ===
 
Standard I/O devices are supported by base physical device drivers that are part of the OS/2 operating system. Additional or replacement physical device drivers can be loaded to extend the control provided by the base device drivers, or to support nonstandard I/O devices. Typical examples of these loadable device drivers are ANSI.SYS and ANSI.DLL, which are loaded by &quot;DEVICE=&quot; statements in the CONFIG.SYS file, and provide additional functions on the interfaces to the screen and keyboard. Physical device drivers are initialized at Ring 3 and operate at Ring 0.


Further information on physical device drivers, physical device driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the ''OS/2 Physical Device Driver Reference''.
Further information on physical device drivers, physical device driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the ''OS/2 Physical Device Driver Reference''.


=== Presentation Drivers ===
=== Presentation Drivers ===
The Presentation Manager* I/O interface for output devices is a high-level interface. This interface is similar to the API (Application Programming Interface) call interface, which uses the program stack to communicate with , or pass parameters to, the presentation drivers. These drivers are special-purpose I/O routines operating with I/O privilege at privilege level 2 (Ring 2) or privilege level 3 (Ring 3). Their main function is to process function calls made by the Presentation Manager interface on behalf of Presentation Manager applications. Hardcopy presentation drivers communicate with OS/2 device drivers through the file system emulation functions. Display presentation drivers interface directly with the hardware.
The Presentation Manager* I/O interface for output devices is a high-level interface. This interface is similar to the API (Application Programming Interface) call interface, which uses the program stack to communicate with , or pass parameters to, the presentation drivers. These drivers are special-purpose I/O routines operating with I/O privilege at privilege level 2 (Ring 2) or privilege level 3 (Ring 3). Their main function is to process function calls made by the Presentation Manager interface on behalf of Presentation Manager applications. Hardcopy presentation drivers communicate with OS/2 device drivers through the file system emulation functions. Display presentation drivers interface directly with the hardware.


Presentation drivers are dynamic link library modules that are supplied as files and are identified by the extension &quot;.DRV&quot;. When the Presentation Manager is initialized, the display presentation driver is automatically loaded and enabled. Other presentation drivers (for example, the hardcopy presentation drivers) are loaded and enabled when an application calls the ''DevOpenDC''function to open the device.
Presentation drivers are dynamic link library modules that are supplied as files and are identified by the extension ".DRV". When the Presentation Manager is initialized, the display presentation driver is automatically loaded and enabled. Other presentation drivers (for example, the hardcopy presentation drivers) are loaded and enabled when an application calls the ''DevOpenDC'' function to open the device.


Presentation drivers service requests only from applications running in Presentation Manager sessions in the OS/2 mode. Output data and requests for information are passed to the presentation driver as function calls to the presentation driver interface. The definition of the call interface is given in terms of the codes and data passed to the presentation driver interface through the program stack.
Presentation drivers service requests only from applications running in Presentation Manager sessions in the OS/2 mode. Output data and requests for information are passed to the presentation driver as function calls to the presentation driver interface. The definition of the call interface is given in terms of the codes and data passed to the presentation driver interface through the program stack.


Include (.INC and .h) files are shipped with the ''Developer's Toolkit for OS /2''to provide support for building presentation drivers that are written in either C or assembler language. These files contain function prototypes, defined values, and data structures used by the various functions.
Include (.INC and .h) files are shipped with the ''Developer's Toolkit for OS /2'' to provide support for building presentation drivers that are written in either C or assembler language. These files contain function prototypes, defined values, and data structures used by the various functions.


Further information on presentation drivers, presentation driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the ''OS/2 Presentation Device Driver Reference''.
Further information on presentation drivers, presentation driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the ''OS/2 Presentation Device Driver Reference''.


==When to Use a Virtual Device Driver ==
==When to Use a Virtual Device Driver ==
 
The device virtualization provided by OS/2 can be extended by creating a virtual device driver (VDD) and the corresponding physical device driver (PDD). A user-supplied virtual device driver virtualizes the hardware interfaces of an option adapter or device, usually to migrate an existing DOS application into the OS/2 DOS environment.
The device virtualization provided by OS/2 can be extended by creating a virtual device driver (VDD) and the corresponding physical device driver ( PDD). A user-supplied virtual device driver virtualizes the hardware interfaces of an option adapter or device, usually to migrate an existing DOS application into the OS/2 DOS environment.


Note that a virtual device driver is needed only in a limited number of cases. If there is no requirement for multiple sessions to share access to a device, a requirement for a virtual device driver is unlikely. OS/2 maps interrupts, I/O ports, and I/O memory directly to any DOS device driver or DOS application which attempts to access these resources. As long as a resource is not already claimed by another session or by the OS/2 kernel, it is directly accessible to the DOS program.
Note that a virtual device driver is needed only in a limited number of cases. If there is no requirement for multiple sessions to share access to a device, a requirement for a virtual device driver is unlikely. OS/2 maps interrupts, I/O ports, and I/O memory directly to any DOS device driver or DOS application which attempts to access these resources. As long as a resource is not already claimed by another session or by the OS/2 kernel, it is directly accessible to the DOS program.
Line 212: Line 86:
In the absence of a sharing requirement, a virtual device driver might be necessary if the device has strict interrupt service latency requirements. A virtual device driver/physical device driver pair improves the interrupt service latency for an option adapter or device.
In the absence of a sharing requirement, a virtual device driver might be necessary if the device has strict interrupt service latency requirements. A virtual device driver/physical device driver pair improves the interrupt service latency for an option adapter or device.


 
==OS/2 Version Compatibility Considerations==
 
 
 
= Virtual Device Driver Architecture and Operations =
 
The architecture and structure of virtual and physical device drivers differ considerably from one another. A physical device driver is considered a true device driver in the sense that it has a unique and rigid file structure, and interfaces directly with the hardware. A virtual device driver is essentially a dynamic link library, and generally does not interface directly with the hardware. Instead, it is responsible for presenting a virtual copy of a hardware resource to a DOS session, and for coordinating physical access to that resource.
 
 
 
 
 
==Virtual Device Driver Architecture ==
 
Virtual device drivers manage I/O ports, device memory, and ROM BIOS services for the devices they virtualize. For hardware compatibility purposes, a virtual device driver should behave as much as possible like the physical hardware. Otherwise, incompatible emulation could result. In the case of system drivers, a virtual device driver should use a physical device driver to manipulate hardware, wherever possible.
 
 
 
 
 
=== Virtual Device Driver Structure ===
 
A virtual device driver is a 32-bit EXE file that may contain some or all of the following types of objects:
 
*Initialization code <br />*Initialization data <br />*Swappable global code <br />*Swappable global data <br />*Swappable instance data <br />*Resident global code <br />*Resident global data <br />*Resident instance data
 
The resident objects must be used for code and data that must be accessible at physical hardware interrupt time, that is, when a physical device driver calls the virtual device driver. A virtual device driver that does not interact with a physical device driver may not need any resident objects.
 
Virtual device drivers conform to the EXE32 Load Module format. A typical virtual device driver has a shared (global) code object, a shared (global) data object, and a private (instance) data object. It is possible for a virtual device driver to have multiple objects of each type. The global code and data objects are addressable in all process contexts. As with instance data for dynamic link libraries, the instance data object is per- DOS session data; that is, the same address in each DOS session context is initialized to the same initial state, but backed by different physical memory. Each object must be equal to or less than 64KB in size.
 
Run-time allocated memory can be allocated as either ''swappable''or ''fixed''. In addition, run-time allocated memory can also be:
 
*Private (per-DOS session), which is allocated out of the DOS session private memory area. This is the preferred method, and is suitable when memory is used only in the context of owning the DOS session. <br />*Shared (global), which is allocated from the system area. This should be used only when the allocation must be created, modified, or freed in an arbitrary process context.
 
 
 
 
 
==Virtual Device Driver Operations ==
 
Virtual device drivers are loaded and initialized before the shell is started, but after all the physical device drivers have been loaded and initialized.
 
 
 
 
 
=== Virtual Device Driver Loading ===
 
After the physical device drivers have been loaded, the DOS Session Manager is initialized (at OS/2 system initialization time), which then initializes the 8086 emulation component, and loads and initializes the virtual device drivers. An initial V86-mode memory map is constructed at this time for later use at DOS session creation.
 
The DOS Session Manager calls the loader to load virtual device drivers. Base virtual device drivers are loaded first, followed by installable virtual device drivers. ''Base''virtual device drivers are those that must be present for multiple DOS sessions to function. ''Installable''virtual device drivers are those specified in the &quot;DEVICE=&quot; lines in the CONFIG.SYS file. The multiple DOS session environment is still operable if any or all of these installable drivers fail to load. The one exception to this rule is the virtual video device driver, which is a base virtual device driver that is loaded in the CONFIG.SYS file.
 
The global code and data objects are loaded into the system area. This is required so that a physical device driver can pass along a hardware interrupt by calling a virtual device driver at interrupt time, regardless of the current process context.
 
The instance data objects are loaded into the address space between 1MB and 4MB for that session. This is the private address space managed by the DOS session. The loader and DOS Session Manager cause this allocation to occur so that the full ''virtual''state of the DOS session is contained below the 4MB line, thus allowing a single Page Directory Entry (PDE) to map a DOS session context. This has two benefits:
 
*Context-switching DOS sessions are fast, because only a single PDE needs to be edited.
 
*It is simple to maintain an alias region in the system area for each DOS session. This alias region is a 4MB-aligned, 4MB region of linear address space, whose base is called a ''DOS session handle'', which can be used in a base register to manipulate the instance data of that DOS session. This is an important feature, as it allows virtual device drivers to quickly access the instance data of any DOS session.
 
The virtual device driver entry point is called after the virtual device driver is loaded. The device driver returns a nonzero value to indicate a successful load, and returns 0 to indicate an unsuccessful load.
 
 
 
 
 
=== Virtual Device Driver Initialization ===
 
After a virtual device driver is loaded, it performs the following operations, as appropriate:
 
*Verifies the presence of corresponding hardware <br />*Establishes communication with the corresponding physical device driver <br />*Reserves regions of linear memory containing device ROM and RAM <br />*Saves the initial physical device state for initializing the virtual device state upon DOS session creation <br />*Set hooks for various DOS session events (creation, termination, foreground/background switch). See [[00594.htm|VDHInstallUserHook]]for a complete list of user hooks.
 
Virtual device drivers are initialized at Ring 0. For this reason, they cannot make Ring-3 API calls, and they only interact with OS/2 through use of the virtual DevHlp services.
 
 
 
 
 
==== Installing User Hooks ====
 
Each virtual device driver must use ''VDHInstallUserHook''to install a VDM_ CREATE hook. Virtual device drivers that use foreground and background (for example, video, keyboard, or mouse) must also install VDM_FOREGROUND and VDM_BACKGROUND hooks. For more information, see [[00594.htm|VDHInstallUserHook]].
 
 
 
 
 
==== Allocating Global Resources ====
 
Global resources are allocated at this time.
 
 
 
 
 
==== Registering Virtual Device Driver for Communications ====
 
When virtual device drivers communicate with the kernel, physical device drivers, other virtual device drivers, or with the Presentation Manager interface, the Dynamic Link mechanism is used to:
 
*Export virtual DevHlp services to virtual device drivers <br />*Export kernel data to virtual device drivers <br />*Export services from one virtual device driver to another
 
To restrict the modifications required for physical device drivers (which remain 16:16), virtual DevHlp services are provided so that a virtual device driver can establish communication with a physical device driver. This is no more than an exchange of entry points. At this point, the physical device driver and the virtual device driver can use any protocol to communicate. Although a suggested protocol is provided in [[00025.htm|Inter-Device- Driver Communication]], device drivers are not restricted to this.
 
 
 
 
 
=== DOS Session Creation and VDD Per-DOS Session Initialization ===
 
When the user starts a DOS application, the DOS Session Manager notifies the virtual device drivers that have registered creation hooks, and gives them an opportunity to do per-DOS session initialization. Memory is allocated and mapped into the V86-mode address space, and the DOS Emulation code is initialized. Control is passed to the DOS Emulation kernel to load the shell specified by DOS_SHELL (usually COMMAND.COM) and the application selected by the user.
 
Virtual device drivers perform the following operations (as appropriate) at DOS session creation time:
 
*Initialize the virtual device state <br />*Initialize the virtual ROM BIOS state <br />*Map linear regions (reserved at virtual device driver initialization time) to physical or linear memory <br />*Hook the I/O ports <br />*Enable or disable the I/O port trapping <br />*Hook the software interrupts <br />*Allocate per-DOS session memory
 
 
 
 
 
==== DOS Session Screen Switching ====
 
The OS/2 Session Manager notifies the DOS Session Manager of screen switches. The DOS Session Manager, in turn, notifies all virtual device drivers that are involved in these events (generally, the video, keyboard, and mouse virtual device drivers). The virtual video device driver (VVIDEO) takes appropriate steps to map in physical or logical video RAM and disable or enable I/O port trapping for the video hardware. The virtual keyboard device driver (VKBD) can set flags to control the reaction to keyboard polling behavior.
 
 
 
 
 
==== DOS Session Destruction ====
 
When a user exits a DOS session, the virtual device drivers are notified to clean up any resources owned by that DOS session (that is, the virtual device driver's DOS session termination entry points are called by the DOS Session Manager). Memory is released and the process is terminated, as is done with a normal OS/2 process. DOS sessions can also be terminated by a virtual device driver if unsupported behavior is detected, or by the DOS emulation component (if it is damaged or is otherwise unable to function).
 
 
 
 
 
=== Local and Global Information Regions ===
 
Most of the information available through information segments can be obtained by a virtual device driver using the virtual DevHlp service ''VDHQuerySysValue''. For further information, see [[00822.htm|VDHQuerySysValue]].
 
 
 
 
 
=== Virtual DevHlp (VDH) Services ===
 
A set of virtual DevHlp (VDH) services is used to provide an abstract but efficient means for virtual device drivers to interact with DOS sessions and the OS/2 kernel. These VDH services have the following characteristics:
 
*They are available through dynamic linking.
 
*They use the 32-bit calling conventions found in the function prototype definition VDHENTRY located in the MVDM.INC and .h include files.
 
*A return value of 0 (zero) usually means that the call failed. When 0 is returned, calling ''VDHGetError''returns a detailed error code. If this return is 0, the last call succeeded and 0 was a meaningful return value, not an error. A nonzero return value means that the call succeeded. See [[00502.htm|VDHGetError]].
 
*All pointer parameters are 0:32 flat pointers.
 
The Memory Management Virtual DevHlp services are used for:
 
*Mapping <br />*Reservation <br />*Allocation/reallocation/free
 
See [[00129.htm|C Language Virtual DevHlp Services]]for a list of the page-granular memory management services and a description of each virtual DevHlp.
 
 
 
 
 
== Inter-Device-Driver Communication ==
 
A virtual device driver can communicate with a physical device driver by using the Inter-device-Driver Communication (IDC) mechanism provided by the OS/2 operating system. A virtual device driver communicates with a physical device driver directly though a callable 16:16 interface, or by using the virtual DevHlp services that map to file system APIs. Virtual device drivers communicate directly with other virtual device drivers by using a set of the virtual DevHlp services.
 
The type and form of communication is defined by the physical or virtual device driver that provides the IDC entry point to be called. These device drivers must be aware of addressability and be sensitive to interrupt-time performance. For example, a virtual device driver that is not reflecting hardware interrupts to applications, and is in communication with a physical device driver, should use the virtual DevHlp services that map to File System APIs to communicate. However, if the virtual device driver must reflect hardware interrupts, the physical device driver should use the 16: 32 callable interface because it provides a more sensitive interface in which to communicate.
 
 
 
 
 
=== Virtual Device Driver and Physical Device Driver Interaction ===
 
Many virtual device drivers virtualize hardware that generates interrupts. Generally, these drivers must interact with a physical device driver to fully virtualize a device. Virtual DevHlp services are provided for the Open, Close, Read, Write, and IOCtl functions of the File System, which is then routed to the corresponding physical device driver. This is the simplest IDC mechanism for VDD/PDD communication.
 
Where interrupt-time or other high-performance PDD/VDD IDC requirements exist, the ''VDHOpenPDD''service is used to establish communication between a virtual device driver and a physical device driver by exchanging entry points, which use a 32-bit calling convention (refer to the multiple DOS session-specific equates found in the MVDM.INC include files). At this point, the virtual device driver and physical device driver are free to communicate through whatever private protocol is chosen, including exchanging register-based entry points. However, both drivers must agree on a shutdown protocol, that is, what is used to stop the communication if the virtual device driver must shut down. See [[00650.htm|VDHOpenPDD]]for more information.
 
 
 
 
 
=== Virtual Device Driver/Virtual Device Driver Communication ===
 
Because dynamic linking is supported between virtual device drivers, multiple virtual device drivers can support inter-virtual device driver communication through dynamic links. Where these device drivers are supplied by multiple parties and it is not required that all of the virtual device drivers in the set be present, dynamic linking does not work. The virtual DevHlp services, ''VDHRegisterVDD'', ''VDHOpenVDD'', ''VDHRequestVDD'', and ''VDHCloseVDD''are used to overcome this limitation of dynamic linking. For details, see [[00908.htm|VDHRegisterVDD]], [[00658.htm|VDHOpenVDD]], [[00966.htm|VDHRequestVDD]], and [[00301.htm|VDHCloseVDD]].
 
 
 
 
 
== Hardware Emulation and Interrupt Support ==
 
The major functions of software interrupt emulation are:
 
*Hook interrupt service: see [[00573.htm|VDHInstallIntHook]]<br />*Return to DOS session interrupt handler service: see [[00742.htm|VDHPushInt]]<br />*Hook return service: see [[00216.htm|VDHArmReturnHook]]
 
 
 
 
 
=== Hook Interrupt Service (VDHInstallIntHook) ===
 
The handler supplied to this service is a ''post-reflection handler''. Post- reflection handlers are called after the INT instruction is reflected into the DOS session interrupt code. A DOS session breakpoint address is put into the interrupt vector table entry at INIT time, so control returns to the kernel at the end of the DOS session's interrupt code chain. The virtual device driver interrupt handler chain is then called. The ROM routine address (or whatever was initially in the interrupt vector table), which was replaced by the DOS session breakpoint, is returned to, if the virtual device driver handlers do not call ''VDHPopInt''. See [[00687.htm|VDHPopInt]].
 
 
 
 
 
=== Return to DOS Session Interrupt Handler Service (VDHPushInt) ===
 
''VDHPushInt''calls the interrupt reflection code to change the DOS session's execution flow to the DOS session's interrupt code. This is done by building a return IRET frame on the client's stack with the CS:IP and flags from the kernel stack frame. The DOS session's CS:IP on the kernel stack is edited with the address from the DOS session's interrupt vector table. See the figure in the next section.
 
 
 
 
 
=== Hook Return Service (VDHArmReturnHook) ===
 
The ''VDHArmReturnHook''service allows the IRET to be hooked after the ''VDHPushInt''service is called. A DOS session breakpoint is allocated, and the address replaces the client's CS:IP on the return IRET frame. The client's CS:IP is saved. For additional information, see [[00208.htm|VDHArmContextHook]]and [[00742.htm|VDHPushInt]]. These services are shown in the following figure.
 
When building the return IRET frame, the client's stack pointer can wrap around from 0 to 0FFFEH. This does not terminate the DOS session. If the client's stack pointer is equal to 1 when this function is begun (before the virtual device driver handlers are called), the DOS session is terminated (to emulate the 386 hardware when it is in real mode).
 
When the virtual device driver installs an interrupt handler, a DOS session breakpoint is installed in the interrupt vector table before any DOS session code hooks. The DOS session breakpoint is executed after the DOS session interrupt code chain is executed but before ROM. The virtual device driver interrupt handlers are executed until one returns the ''stop chaining''indication, or the end-of-list is reached. ROM code is executed after the last virtual device driver handler is called unless one of these handlers calls ''VDHPopInt''. See [[00687.htm|VDHPopInt]]. This service emulates the IRET when a V86 code interrupt handler has popped off the IRET frame and restored the DOS session's CS, IP, and flags to the IRET frame contents. ''VDHPushInt''is used by the software interrupt instruction trap and by the virtual PIC device driver in the last stages of simulating hardware interrupts.
 
<pre class="western">
Kernel Stack        Client Stack      Kernel Stack      Client Stack
/------------\                        /--------------\    /------------\
|  0  |  SS  |                        |      |  SS  |    |  Flags    |
|------------|                        |--------------|    |------------|
|    ESP    |                        |    ESP      |    |    CS    |
|------------|                        |--------------|    |------------|
|  EFlags  |                        |    EFlags    |    |    IP    |
|------------|                        |--------------|    \------------/
|  0  |  CS  |                        |      |INT CS |
|------------|                        |--------------|
|    IP    |                        |    INT IP    |
\------------/                        \--------------/
Before VDHPushInt                    After VDHPushInt
 
 
  Kernel Stack      Client Stack
/--------------\    /------------\
|  0  |  SS  |    |  Flags    |
|--------------|    |------------|
|      ESP    |    |  VDMBP CS  |
|--------------|    |------------|
|    EFlags    |    |  VDMBP IP  |
|--------------|    \------------/
|  0  |INT CS |
|--------------|
|    INT IP    |
\--------------/
After VDHArmReturnHook
</pre>
 
 
 
 
==== Access to Ports Not Trapped by a Virtual Device Driver ====
 
In order to support DOS applications that use hardware that does not have virtual device drivers, a mechanism is provided for DOS applications to access ports on those devices. This is done by having the default handler for each I/O port turn trapping OFF for the port in question. All accesses after the first one go straight through to the hardware. This is done only for ports that are not trapped by a virtual device driver.
 
 
 
 
 
==== Global and Local Context Hooks ====
 
''Global context hooks''are a mechanism to delay work until the CPU is at task time (as opposed to interrupt time). If a global context hook is set at task time, the handler is called immediately. ''Local context hooks''are a mechanism to delay work until the CPU is at task time in the context of a specific process. When a virtual device driver sets a local context hook, that hook is guaranteed to execute before any user code (that is, code executing in V86 mode).
 
 
 
 
 
== Interrupts Supported by Multiple DOS Sessions ==
 
The following interrupts are supported by multiple DOS sessions:
 
*BIOS hardware interrupt support <br />*BIOS software interrupt support <br />*DOS software interrupt support <br />*Other software interrupt support
 
 
 
 
 
=== BIOS Hardware Interrupt Support ===
 
In previous versions of the OS/2 operating system, DOS applications were prevented from hooking hardware interrupts when the IRQ level was owned by an OS/2 device driver. A DOS application that violated this rule was terminated. In the current version of OS/2 this restriction is significantly relaxed. Depending on the support provided by the device's virtual device driver, DOS applications can now hook the hardware interrupt vector. The following list summarizes the support provided by OS/2 virtual device drivers for each of the hardware interrupt request (IRQ) levels:
 
IRQ 0 '''Timer (INT 08h)'''. The INT 08h handler is invoked on hardware interrupts from Channel 0 of the system timer. DOS applications can hook this interrupt. See the description of INT 08h in [[00037.htm|BIOS Software Interrupt Support]].
 
IRQ 1 '''Keyboard (INT 09h)'''. The INT 09h handler is invoked upon the make or break of every keystroke. DOS applications can hook this interrupt.
 
IRQ 2 '''The Cascade (Slave) Interrupt Controller'''. This controller supports interrupt request levels 8 through 15, as described below.
 
IRQ 3 '''Serial Ports (COM2, 3, 4)'''. These ports are supported when the virtual and physical COM device drivers are installed.
 
IRQ 4 '''Serial Port (COM1)'''. This port is supported when the virtual and physical COM device drivers are installed.
 
IRQ 5 '''Parallel Port 2'''. This hardware interrupt is simulated in DOS sessions .
 
IRQ 6 '''Diskette'''. This hardware interrupt is not simulated in DOS sessions. See the description of INT 0Eh in [[00037.htm|BIOS Software Interrupt Support]].
 
IRQ 7 '''Parallel Port 1'''. This hardware interrupt is simulated in DOS sessions .
 
IRQ 8 '''Real-Time Clock'''. This hardware interrupt is not simulated in DOS sessions. See the description of INT 70h in [[00037.htm|BIOS Software Interrupt Support]] .
 
IRQ 9 '''Redirect Cascade'''. A virtual device driver to simulate this hardware interrupt is not provided.
 
IRQ 10 '''Reserved'''. A virtual device driver to simulate this hardware interrupt is not provided. See [[00036.htm|Reserved IRQ Support in OS/2]]for more information.
 
IRQ 11 '''Reserved'''. A virtual device driver to simulate this hardware interrupt is not provided. See [[00036.htm|Reserved IRQ Support in OS/2]]for further information.
 
IRQ 12 '''Auxiliary Device'''. A virtual device driver to simulate this hardware interrupt is not provided. See [[00036.htm|Reserved IRQ Support in OS/2]]for further information.
 
IRQ 13 '''Mathematics Coprocessor (NPX)'''. NPX exception interrupts on IRQ 13 are reflected into the DOS session.
 
IRQ 14 '''Fixed Disk'''. This hardware interrupt is not simulated in DOS sessions .
 
IRQ 15 '''Reserved'''. A virtual device driver to simulate this hardware interrupt is not provided. See [[00036.htm|Reserved IRQ Support in OS/2]]below for more information.
 
 
 
 
 
==== Reserved IRQ Support in OS/2 ====
 
The OS/2 operating system does not provide support for optional devices on the ''Reserved''and ''Redirect Cascade''interrupt levels in OS/2-mode sessions, or in DOS sessions. Hooking one of these hardware interrupt request levels in a DOS application has no effect. If there is no physical device driver/ virtual device driver pair to service an interrupt, the DOS application's interrupt handler is not invoked, even though the hardware interrupts are generated.
 
These hardware interrupt request levels can be supported in a DOS session by a user-installed virtual device driver. However, a user-installed physical device driver is also required to provide this support since there is no mechanism for a virtual device driver to directly service a hardware interrupt.
 
 
 
 
 
=== BIOS Software Interrupt Support ===
 
BIOS software interrupt compatibility considerations and restrictions for OS/2 DOS sessions are shown below. Notice that only specific compatibility considerations and functional restrictions for users of BIOS in the DOS session environment of the OS/2 operating system are listed.
 
02h '''Nonmaskable Interrupt (NMI)'''. Not reflected to the DOS sessions; this BIOS interrupt handler is not invoked on NMI.
 
05h '''Print Screen'''. The BIOS INT 05h handler is supported. If the DOS application issues INT 05h, the contents of the video buffer is printed. The '''Shift+PrtScr'''keystroke combination (or equivalent) also invokes this function.
 
08h '''System Timer'''. This interrupt is invoked every time the system timer Channel 0 counts down to zero (normally, 18.2 times per second). DOS applications can hook this interrupt. However, in a DOS session these timer interrupts can come in a burst and have variable latency. The INT 08h interrupt handler is emulated by the virtual timer device driver.
 
0Eh '''Diskette'''. The INT 0Eh handler is not used to service interrupts generated by the diskette device (IRQ 6). DOS applications should not hook this interrupt.
 
10h '''Video'''. The INT 10h functions are fully supported in DOS sessions. The following INT 10h functions are emulated by the virtual video device driver .
 
0Eh Write Teletype (TTY) <br />13h Write String
 
'''Note:'''These functions are emulated only if the INT 10h vector is unmodified. If any piece of DOS session code hooks INT 10h, emulation occurs only if these functions are passed to the virtual video device driver's interrupt hook.
 
13h '''Hard Disk/Diskette'''. INT 13h emulation in a DOS session supports both removable and nonremovable media. The following subset of INT 13h functions are supported in DOS sessions:
 
00h Reset Diskette <br />01h Read Status <br />02h Read Sectors <br />03h Write Sectors (Diskette only) <br />04h Verify Sectors <br />05h Format Track (Diskette only) <br />08h Get Drive Parameters <br />0Ah Read Long (Fixed Disk only) <br />15h Read DASD Type <br />16h Change Status (Diskette only) <br />17h Set Disk Type (Diskette only) <br />18h Set Media Type (Diskette only)
 
14h '''ASYNC'''. When the virtual COM device driver is installed, all BIOS INT 14h functions are supported. These functions are emulated by the virtual COM device driver to enhance performance:
 
00h Initialize Port <br />01h Send Character <br />02h Receive Character <br />03h Read Status <br />04h Extended Initialize <br />05h Extended Port Control
 
15h '''System Services'''. These services are listed in the following table:
 
<pre class="western">/--------------------------------------------------------------\
|AH|Function                |Description                      |
|--+------------------------+----------------------------------|
|00|Cassette Motor ON      |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|01|Cassette Motor OFF      |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|02|Cassette Read          |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|03|Cassette Write          |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|0F|Format Periodic INT    |Error. On return, CF is set.      |
|--+------------------------+----------------------------------|
|4F|Keyboard Intercept      |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|80|Open Device            |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|81|Close Device            |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|82|Program Terminate      |Default. Routed to ROM BIOS.      |
|--+------------------------+----------------------------------|
|83|Event Wait              |Support. Supported  by  VTIMER .      |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 84 | Joystick  Support          | Default .  Routed  to  ROM  BIOS .        |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 85 | SysReq  Key  Pressed        | Support .  Issued  by  VKBD .  On        |
|    |                            | return ,  AL = 0  ( key  make ) ,  or  AL = 1    |
|    |                            | ( key  break ) .                          |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 86 | Wait                      | Support .  Supported  by  VTIMER .      |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 87 | Move  Block                | Error .  Managed  by  VXMS .              |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 88 | Get  Extended  Memory  Size | Error .  Managed  by  VXMS .  On  return , |
|    |                            | AX = 0  ( no  Extended  Memory ) .          |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 89 | Switch  to  Protect  Mode    | Error .  On  return ,  AX  ! = 0  ( fail      |
|    |                            | switch ) .                              |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 90 | Device  Wait                | Default .  Routed  to  ROM  BIOS .        |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| 91 | Device  Post                | Default .  Routed  to  ROM  BIOS .        |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| C0 | Get  System  Config  Parms  | Default .  Routed  to  ROM  BIOS .        |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| C1 | Get  EBIOS  Data  Area      | Default .  Routed  to  ROM  BIOS .        |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| C2 | PS / 2  Mouse  Functions      | Error .  On  return ,  CF  is  set ,  and    |
|    |                            | AH = 01  is  an  invalid  function .      |
|    |                            | Notice  that  all  mouse  support  is    |
|    |                            | through  INT  33h .                    |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| C3 | Watchdog  Timeout          | Ignore .  On  return ,  CF  is  clear .    |
| -- + ---------- ---------- ---- + ---------- ---------- ---------- ---- |
| C4 | Prog  Option  Select        | Default .  Routed  to  ROM  BIOS .        |
\ -- - ---------- ---------- ---- - ---------- ---------- ---------- ---- / </pre>
16h '''Keyboard'''. The keyboard is supported directly by the ROM BIOS INT 16h routines.
 
17h '''Printer'''. The printer is supported (emulated) by the virtual parallel port device driver.
 
19h '''Restart'''. Restart (reboot) is supported. However, this does not operate in the same manner as DOS (the system is not restarted). If the DOS setting DOS_STARTUP_DRIVE is set, the diskette or image restarts. Otherwise, the DOS session is terminated.
 
1Ah '''Time-of-Day'''. The virtual CMOS device driver component supports read- only access to the Real-Time Clock device. Because of this restriction, the following BIOS INT 1Ah functions are not supported in a DOS session:
 
01h Set RTC Count <br />03h Set RTC Time <br />05h Set RTC Date <br />06h Set RTC Alarm <br />07h Reset RTC Alarm <br />08h Set RTC Activated Power-on mode <br />0Bh Set System Timer Day Counter <br />80h Setup Sound Multiplexer
 
A DOS application can read the Real-Time Clock Count, Time, and Date. The INT 1Ah functions are not emulated by the virtual CMOS device driver. Instead, the BIOS ROM functions are executed directly. The CMOS/RTC hardware is virtualized by the virtual CMOS device driver.
 
1Eh '''Diskette Parameters'''. The segment address of the diskette parameters table is stored in the INT 1Eh entry.
 
70h '''Real-Time Clock Interrupt'''. Interrupts from the Real-Time Clock (IRQ 8) are not reflected into DOS sessions. This software interrupt handler is not used for either alarm or periodic interrupts.
 
 
 
 
 
=== DOS Software Interrupt Support ===
 
The DOS emulation component supports the documented aspects of the following DOS features:
 
20h '''Program Terminate'''.
 
21h '''DOS Function Request'''. All documented and undocumented INT 21h functions are supported by DOS emulation. However the following functions are supported, with restrictions:
 
4410h <br />4411h <br />4B05h <br />5Dh <br />5Eh <br />5Fh <br />64h <br />69h <br />6Dh <br />6Eh
 
'''Note:'''Function 53h is not supported by DOS emulation.
 
22h '''Terminate Address'''.
 
23h '''Ctrl+Break Exit Address'''.
 
24h '''Critical Error Handler'''.
 
25h '''Absolute Disk Read'''.
 
26h '''Absolute Disk Write'''. A hard error is reported on requests for nonremovable media.
 
27h '''Terminate-and-Stay-Resident'''.
 
28h '''Idle Loop'''.
 
2Fh '''Multiplex'''. Time slice yield (AX = 1680h) is supported. When a DOS application issues INT 2Fh with AX = 1680h, it offers to yield its time slice. This can be used by DOS applications in busy wait loops (preserves all registers).
 
 
 
 
 
=== Other Software Interrupt Support ===
 
The following are other software interrupts supported in an OS/2 DOS session:
 
 
 
 
 
=== INT 33h - Mouse ===
 
Supported. When the OS/2 virtual mouse driver is installed, the full range of INT 33h functions, as defined in the ''Microsoft Mouse Programmer's Reference Guide''are available.
 
 
 
 
 
=== INT 4Bh - Virtual DMA Services (VDS) - Function 81h ===
 
Supported. When the OS/2 virtual DMA device driver is installed, the VDS INT 4Bh functions as defined in the ''Microsoft Virtual DMA Services Specification, Version 1.0''are available.
 
 
 
 
 
=== INT 67h - LIM Expanded Memory Manager (EMM) ===
 
Supported. When the OS/2 virtual expanded memory manager device driver is installed, the LIM EMM V4.0 INT 67h functions as defined in the ''Lotus/Intel /Microsoft Expanded Memory Specification, Version 4.0''are available.
 
 
 
 
 
=Base Virtual Device Drivers=
 
The following list contains all the base virtual device drivers included with OS/2:
 
*Virtual BIOS device driver (VBIOS) <br />*Virtual CMOS device driver (VCMOS) <br />*Virtual direct memory access device driver (VDMA) <br />*Virtual diskette device driver (VFLPY) <br />*Virtual hard disk device driver (VDSK) <br />*Virtual keyboard device driver (VKBD) <br />*Virtual numeric coprocessor device driver (VNPX) <br />*Virtual parallel port device driver (VLPT) <br />*Virtual programmable interrupt controller device driver (VPIC) <br />*Virtual timer device driver (VTIMER)
 
=== Virtual BIOS Device Driver ===
 
The virtual BIOS device driver (VBIOS) contains the mechanism to initialize the Interrupt Vector table, BIOS data area, extended BIOS data area (on a PS/2* personal computer adapter ROM area), and the system ROM. It also provides virtual access to Programmable Option Select (POS) registers (on a PS/2 personal computer) and supports some of the DOS settings.
 
 
 
 
 
=== DOS Session Creation ===
 
When a DOS session is created, the virtual BIOS device driver is responsible for allocating and initializing the following areas in the DOS session's address space with the respective values from physical memory:
 
*Interrupt Vector Table <br />*BIOS data area <br />*DOS communications area <br />*Extended BIOS data area (on a PS/2 personal computer).
 
The virtual BIOS device driver is also responsible for mapping the system ROM and adapter ROM into the address space of the DOS session. The per-DOS session copy of the POS registers is initialized at this time.
 
 
 
 
 
=== DOS Settings ===
 
The virtual BIOS device driver is responsible for Include/Exclude region support. The DOS setting MEM_INCLUDE_REGIONS gives the user an option to give more space to EMM/XMS. If the user knows that in a particular DOS session an adapter will not be used, then the linear region taken by that adapter can be given to EMM and XMS through MEM_INCLUDE_REGIONS. MEM_ EXCLUDE_REGIONS gives the user an option to restrict EMM and XMS from claiming a particular region. Both these options are provided through DOS settings. These DOS settings are only applicable at DOS session creation time.
 
 
 
 
 
=== Adapter ROM ===
 
At system initialization, the virtual BIOS device driver searches the region between the top of the DOS user space (RMSIZE) and 1MB to find all of the adapter ROM. Adapter ROMs that include the ROM signature will be found. In a normal DOS session creation (without any Include/Exclude properties specified), these linear addresses are mapped to corresponding physical ROM.
 
All the ranges specified in the DOS setting MEM_INCLUDE_REGIONS are taken out of the list used for mapping the linear addresses to corresponding physical ROM. As a result, MEM_INCLUDE_REGIONS is not mapped to physical ROM and it remains available to EMM or XMS.
 
For MEM_EXCLUDE_REGIONS, the virtual BIOS device driver reserves those regions and maps them to their corresponding physical addresses. This allows the user the ability to map adapter ROM that does not contain the ROM signature and adapter RAM.
 
 
 
 
 
=== Virtual CMOS Device Drivers ===
 
The virtual CMOS device driver consists of virtual support for the CMOS battery backed-up RAM, the Real-Time Clock (RTC) and the Nonmaskable Interrupt (NMI) disable logic. It provides virtual access to the address and data latches through virtual I/O ports. This component allows the majority of existing DOS applications that access its ports by direct access, or by normal BIOS calls, to operate without change.
 
 
 
 
 
=== Supported Functions ===
 
The following functions are supported by the virtual CMOS device driver:
 
*CMOS memory access <br />*I/O port support <br />*NMI-disable <br />*Read time-of-day and date <br />*Real-Time Clock and interrupt access
 
 
 
 
 
=== CMOS Memory Access ===
 
CMOS Memory Access provides support for passive reads and writes to virtual CMOS memory. The CMOS portion of the CMOS/RTC can be read or written. The virtual CMOS memory is initialized to the contents of the physical CMOS memory (at the time of DOS session initialization) through the physical clock device driver, which is the physical device driver of the virtual CMOS component. Values are written to the virtual CMOS memory in a buffer local to the DOS session. Unlike the physical CMOS memory, however, the contents of the virtual CMOS memory are lost when the DOS session is terminated.
 
 
 
 
 
=== Input/Output Port Support ===
 
The virtual CMOS device driver component monitors all accesses to its two DOS session I/O ports. The two ports are a write-only address latch and a read/write data latch. The address latch port has two functions, NMI Disable and CMOS/RTC Device Address Selection. The data latch is a register for holding a byte being transferred to or from the CMOS/RTC device.
 
 
 
 
 
=== Disabling Nonmaskable Interrupts ===
 
The Nonmaskable Interrupt (NMI)-Disable portion of the the address latch can be set or reset by a DOS application. However, changes to enable or disable NMI are otherwise ignored.
 
 
 
 
 
=== Read Time-of-Day and Date ===
 
This function presents the correct seconds, minutes, and hours to an application reading the appropriate locations. This function also provides atomic access to all values to avoid reading the values during time transition.
 
 
 
 
 
=== Real-Time Clock and Interrupt Access ===
 
The Real-Time Clock consists of a time-of-day clock, an alarm interrupt, and a periodic interrupt. Accesses to the Real-Time Clock to change the time of day or the timing mode, or to set an alarm or periodic interrupt, are disallowed. The CMOS/RTC registers related to the Real-Time Clock are supported for read-only access. Because interrupts can only be supported through write access to the ports, Real-Time Clock interrupts are not supported.
 
 
 
 
 
=== BIOS Support ===
 
The virtual CMOS device driver component does not emulate BIOS functions. Instead, it allows the existing BIOS functions to be used without change.
 
 
 
 
 
=== Unsupported Functions ===
 
From the perspective of the DOS session, the virtual CMOS device driver component supports access to I/O address space only. Therefore, the following functions are not supported:
 
*Set Time-of-Day and Date <br />*Set Time-of-Day Alarm <br />*Set/Enable Periodic Interrupt <br />*Enable Update Interrupt
 
 
 
 
 
=== Virtual Direct Memory Access Device Driver ===
 
The virtual direct memory access device driver (VDMA) provides per-DOS session per-direct memory access (DMA) channel virtualization. In addition, the virtual DMA device driver provides the following:
 
*Serializes the DOS session's DMA requests on a per-DMA channel basis (but allows simultaneous requests on different DMA channels)
 
*Converts the DOS session's linear addresses to physical addresses, and handles all the data movement required
 
*Handles all the restrictions of a DMA chip
 
*Supports the enhanced DMA operations and commands of a personal computer
 
*Optimizes DMA virtualization on personal computers by using the enhanced mode
 
*Supports INT 4Bh - Function 81h virtual DMA services
 
*Supports virtualized DMA in auto-initialization mode
 
In addition to the above features, the virtual DMA device driver also synchronizes the operations with other virtual device drivers registered on different DMA channels. A virtual device driver for a piece of hardware, which uses a DMA channel, registers with the virtual DMA device driver. The virtual device driver informs these virtual device drivers before starting and stopping the DMA operation on their channels.
 
 
 
 
 
=== Virtual Diskette Device Driver ===
 
The virtual diskette device driver (VFLPY) intercepts applications that try to access the diskette drive directly or issue INT 13h calls. This virtual device driver also serializes and coordinates I/O operations between multiple DOS sessions.
 
 
 
 
 
=== Obtaining Physical Diskette Hardware Ownership ===
 
When the system first starts up, the physical diskette device driver owns the physical diskette hardware. All diskette accesses from the OS/2 applications go through the file system or the physical diskette device driver, and are eventually serialized into requests. Initially, the virtual hard disk device driver does not own the diskette controller, and it hooks all the diskette ports. It requests ownership from the physical diskette device driver when the DOS session accesses any diskette port, or when the virtual DMA device driver informs the virtual hard disk device driver that the diskette DMA channel has been unmasked. If the immediate ownership request is not successful, the DOS session is blocked until the physical diskette device driver calls back and grants the ownership.
 
 
 
 
 
=== Releasing Physical Diskette Hardware Ownership ===
 
Once the virtual diskette device driver has obtained the diskette ownership , it does not release ownership until the physical diskette device driver requests it, or the diskette motor is turned OFF.
 
 
 
 
 
=== Physical Diskette Interrupt Routing ===
 
Physical diskette interrupts are always routed to the physical device driver by the interrupt manager. If the virtual diskette device driver has the exclusive hardware ownership when the interrupt happens, the physical diskette device driver routes the event to the virtual diskette device driver, which simulates the interrupt to the DOS session.
 
 
 
 
 
=== Virtual Hard Disk Device Driver ===
 
The virtual hard disk device driver (VDSK) provides virtual disk support for multiple DOS sessions and supports access to the disk through BIOS (INT 13h) calls. Since BIOS accesses the hardware ports directly, the virtual hard disk device driver component overrides the BIOS by directly emulating INT 13h for hard disks. The virtual hard disk device driver component does not provide I/O port level access to the disk controllers. Access to hardware ports that are supported for the diskette drive, and BIOS INT 13h calls, are not emulated; instead, they are run from the actual BIOS. INT 13h support includes:
 
AH=00h Reset diskette system <br />AH=01h Status of disk system <br />AH=02h Read sectors into memory (both diskette and hard disk) <br />AH=03h Write sectors from memory (diskette only) <br />AH=04h Verify sectors (both diskette and hard disk) <br />AH=05h Format track (diskette only) <br />AH=08h Get current drive parameters (both diskette and hard disk) <br />AH=0Ch Seek <br />AH=15h Get disk type (both diskette and hard disk) <br />AH=16h Change of disk status (diskette only) <br />AH=17h Set disk type (diskette only) <br />AH=18h Set media type for format (diskette only)
 
The INT 13h emulator is also responsible for maintaining the diskette and hard disk areas of the ROM BIOS data area.
 
Typical steps of an INT 13h access are listed below:
 
*A DOS application accesses the disk through the INT 13h interface. The INT 13h call is trapped by the virtual hard disk device driver.
 
*A request packet is built and sent to the physical hard disk device driver . The DOS session is then blocked, waiting for the request to finish.
 
*Upon receiving the request packet, if the disk is currently busy, the physical hard disk device driver queues the request.
 
*When the request is completed, the physical device driver notifies virtual device driver, which unblocks the DOS session.
 
Because the virtual hard disk device driver component does not support register level accesses of the disk controller, all accesses to its registers are trapped and ignored.
 
'''Note:'''Timing-related copy protection can fail because real-time access is not guaranteed. Sector WRITE and FORMAT requests are not supported for hard disk. Sector WRITE and FORMAT operations are supported for diskette.
 
 
 
 
 
=== Virtual Numeric Coprocessor Device Driver ===
 
The virtual numeric coprocessor device driver (VNPX) provides virtual coprocessor (80 x 87) support for multiple DOS sessions. The virtual numeric coprocessor device driver coordinates exception and interrupt reflection for the real coprocessor. Machines with the 80386 B1 processor, or without a coprocessor, do not have coprocessor support.
 
 
 
 
 
=== Virtual Keyboard Device Driver ===
 
The virtual keyboard device driver (VKBD) consists of virtual support for the keyboard. It allows keystrokes to be passed from the keyboard to the DOS session and text to be pasted from another application into the DOS session as keystrokes. This virtual device driver also allows existing DOS applications that access the keyboard to operate without change. Such applications can access the keyboard through BIOS calls, access to the BIOS data area, or monitoring of the keyboard interrupt, and reading keystroke data directly from the I/O ports.
 
The virtual keyboard device driver addresses the following issues:
 
*'''INT 21h Access'''. DOS applications can access the keyboard by opening the &quot; CON:&quot; (console) device, or by default standard input access.
 
*'''BIOS Access'''. DOS applications can access the keyboard through BIOS INT 09h and INT 16h.
 
*'''I/O Port Access'''. DOS applications can access the keyboard by reading and writing I/O ports 60h and 64h. This access is not restricted to reading scan codes, and can include other types of access (such as LED control).
 
*'''Pasting'''. Data can be pasted from other OS/2 applications.
 
*'''Internationalization'''. Keystrokes are translated according to the current keyboard translation table and code page.
 
*'''Idle Detection'''. DOS applications must not waste excessive CPU time when in input peek loops.
 
 
 
 
 
=== Levels of I/O Support ===
 
The various levels of support for the virtual keyboard device driver are as follows:
 
*BIOS support <br />*CON device driver support <br />*DOS support <br />*Idle detection support <br />*I/O port support <br />*Pasting support
 
 
 
 
 
=== BIOS Support ===
 
Since the BIOS INT 16h service only references the BIOS data area for keystrokes, the BIOS continues to provide this service.
 
The BIOS INT 09h interrupt service routine, however, is emulated within the virtual keyboard device driver. When the INT 09h vector is invoked, the virtual keyboard device driver passes the character to the physical device driver, which translates the character according to the current translation table.
 
It is possible for an application or a DOS memory-resident program to hook the INT 09h vector. Often, such applications simply monitor keystrokes, and pass them on to the previously-hooked interrupt service routine. In this case, the virtual keyboard device driver emulation code still runs and translates scan codes according to the current translation table. Otherwise , if an application that has hooked INT 09h fails to pass the scan code on, then the scan code is not translated, or placed into the BIOS data area by the virtual keyboard device driver.
 
 
 
 
 
=== CON Device Driver Support ===
 
This support consists of allowing the virtual console device driver to be replaced. Although the default virtual console device driver. restricts keyboard access to BIOS calls, user-supplied drivers can access the keyboard through I/O ports or through the BIOS data area.
 
 
 
 
 
=== DOS Support ===
 
This support consists of keyboard access through the various INT 21h functions. In particular, this is support for access from the DOS emulation component. For compatibility, DOS calls the virtual console device driver to read keystrokes. This allows the virtual console device driver to be replaced without ill effect.
 
 
 
 
 
=== Idle Detection Support ===
 
DOS applications waste CPU time in a multitasking system when they peek for input in a loop. Idle conditions are detected when:
 
*The application is polling the keyboard using INT 16h in a loop <br />*DOS is polling in an input loop <br />*Repeated INT 28h calls are received from a DOS application <br />*INT 2Fh, AX=1680h yield calls are received <br />*DOS INT 21h, service 0Bh calls are received
 
Two services are available to device drivers to assist and for handling, [[00951.htm|VDHReportPeek]]and [[01126.htm|VDHWakeIdle]].
 
 
 
 
 
=== I/O Port Support ===
 
The virtual keyboard device driver is responsible for supporting programs that access the keyboard ports directly. These ports provide access to data ports on the hardware that controls I/O to the keyboard. This support is provided primarily for applications that simply read the scan code directly from the port. However, other functions are possible, such as setting the key repeat rate. Repeat rates affect the entire system; per-DOS session repeat rates are not supported. Extended scanner functions, such as providing keyboard pre-controller translation, are not supported; such commands are ignored.
 
 
 
 
 
=== Pasting Support ===
 
The virtual keyboard device driver supports two levels of pasting from the clipboard into a DOS session; ''fast pasting''and ''slow pasting''. In fast pasting support, characters from the clipboard are put directly into the BIOS buffer. For those DOS applications that get their key strokes from the BIOS key buffer (through INT 16h), fast pasting is adequate. For those DOS applications that hook INT 09h or INT 15h (AH=4Fh), key scan sequences are expected, which must be generated by the slow pasting mechanism.
 
In slow pasting, every character from the clipboard is reverse translated into scan sequence and can involve generating make-and-break scans of not only the character itself, but also the make and break of the shift keys in order to adjust the upper, lower, or control case of the character. It can even involve generating '''Alt+numeric keypad'''scan sequences for those characters, which cannot be directly typed on the keyboard (such as graphics characters or international characters).
 
 
 
 
 
=== Virtual Programmable Interrupt Controller Device Driver ===
 
The virtual PIC device driver (VPIC) is responsible for the virtualization of the 8259 Programmable Interrupt Controller (PIC) for multiple DOS sessions and for the simulation of interrupts to DOS sessions. Performance is a major requirement for hardware interrupt simulation. In this book, ''hardware interrupt''and ''interrupt''have the same meaning. ''Simulated interrupt'' , ''interrupt simulation'', and ''hardware interrupt simulation''all refer to the virtual PIC device driver sending an interrupt to a DOS session.
 
The virtual PIC device driver supports the hardware interrupt-related services needed by virtual device drivers and DOS sessions. The services include setting handlers to trap EOI and IRET events, simulating interrupts to DOS sessions, and handling PIC I/O accesses by DOS sessions. See [[00150.htm|Virtual Interrupt Services]]for a list of these virtual DevHlp services. The virtual PIC device driver maintains a per-DOS session virtual PIC state so that each DOS session appears to have its own independent 8259 Programmable Interrupt Controller. Provisions are included to demand page DOS sessions interrupt handling code. The virtual PIC device driver provides a DOS session with the following services:
 
*Virtualization of the 8259 PIC ports:
 
-Separate master and slave PICs <br />-Mask and unmask IRQ commands <br />-Specific and nonspecific EOI commands <br />-Read IR and IS register commands
 
*Hardware interrupts that can be be postponed until task time so that a DOS session can be paged
 
*Interrupts from an optional hardware adapter, which does not have a virtual device driver and a physical device driver, that can be simulated to a DOS application
 
The virtual PIC device driver provides virtual device drivers with:
 
*A high-performance mechanism to send hardware interrupts to DOS sessions:
 
-Support for more than one virtual device driver to share an interrupt level <br />-Support for a virtual device driver to regain control when a DOS session issues EOI commands, or when a DOS session executes the IRET at the end of the interrupt routine
 
*A mechanism for virtual device drivers to send a virtual EOI to the virtual PIC device driver
 
*A way to block until an interrupt is simulated
 
*A mechanism to query a DOS session's virtual IRQ state or status:
 
-Masked or unmasked state (IMR) <br />-Waiting to be sent to a DOS session state (IRR) <br />-Executing DOS session's interrupt handler code state (ISR) <br />-Pending interrupt routine IRET state
 
Hardware interrupt simulation is closely tied to the PIC virtualization. Virtual device drivers need a fast mechanism to call a DOS session's real- mode interrupt handler for a hardware interrupt. Because paging of DOS sessions (and therefore DOS session interrupt handlers) is required, simulated interrupts are delayed until the task-time context of the target DOS session.
 
 
 
 
 
=== Virtual Timer Device Driver ===
 
The virtual timer device driver (VTIMER) provides virtual timer support for multiple DOS sessions. This virtual timer device driver emulates the Intel* * 8254A Programmable Interval Timer.
 
 
 
 
 
=== DOS Support ===
 
The virtual timer device driver provides the following:
 
*Virtualization of timer ports to allow reprogramming of the interrupt rate and the speaker tone frequency <br />*Distribution of timer ticks to DOS sessions <br />*Maintenance of the timer tick count in the BIOS data area <br />*Serialization of Timer 0 and Timer 2 between the virtual timer device driver and the physical timer device driver
 
 
 
 
 
=== Virtual Parallel Port Device Driver ===
 
The virtual parallel port device driver (VLPT) consists of virtual support for direct hardware access to the three parallel ports (LPT1, LPT2, and LPT3), and for the printer-related BIOS entry points (Printer I/O INT 17h, Print Screen INT 05h). Existing DOS applications that access the parallel ports, either by direct access to the ports or by printer BIOS, operate without change. The VLPT provides the virtualization to allow multiple DOS applications to access virtual printer hardware simultaneously. This virtual device driver, in conjunction with the spooler, attempts to prevent multiple DOS applications that transmit data by using BIOS functions or direct hardware access, from intermixing output at the parallel port.
 
The virtual parallel port device driver consists of several sections:
 
*BIOS INT 17h Emulation <br />*BIOS INT 05h Emulation <br />*Printer Close Processing <br />*Direct I/O Access
 
 
 
 
 
=== BIOS INT 17h Emulation ===
 
One method DOS applications can use to send data to a printer is to use BIOS interrupt 17h. The VLPT emulates BIOS INT 17h and passes these requests through the file system to the physical parallel port device driver (PLPT) by using the system services ''VDHOpen'', ''VDHWrite''and ''VDHClose''. See [[00636.htm|VDHOpen]]. [[01140.htm|VDHWrite]], and [[00294.htm|VDHClose]]. These functions are not passed to the BIOS for processing.
 
The BIOS INT 17h emulation supports three functions:
 
*'''Print Character'''. The Print Character function buffers single character requests in the virtual device driver buffer associated with each device in a DOS session. When the buffer becomes full, its contents are sent to the VLPT by using ''VDHWrite''. If the device is not open, the VLPT issues ''VDHOpen''to obtain a file handle and start a printer data stream. See [[01140.htm|VDHWrite]]and [[00636.htm|VDHOpen]].
 
*'''Initialize'''. The virtual parallel port device driver buffer is sent to the physical parallel port device driver by using ''VDHWrite''. The printer data stream is closed by using ''VDHClose''. See [[01140.htm|VDHWrite]]and [[00294.htm|VDHClose]].
 
When the spooler is enabled, closing the data stream closes the spool file. Any subsequent printing will open a new spool file. The beginning of the spool file contains escape sequences to reset the printer to its power-on defaults. When the spooler is disabled, no initialization of the device takes place.
 
*'''Read Status'''. The Read Status function returns the contents of the virtual device status register.
 
See [[00078.htm|Printer Close Processing]]for the possible methods of closing a printer data stream opened with BIOS INT 17h.
 
 
 
 
 
=== BIOS INT 05h Emulation ===
 
The method used to send data from the display to the printer (LPT1) is to press the '''Print Screen'''key. DOS applications can also initiate a Print Screen function by issuing a call to a BIOS INT 05h function. The virtual parallel port device driver passes this request to BIOS for processing. The virtual device driver performs some special processing to prevent the INT 05h request from intermixing with an INT 17h print request to the same device. Also, two BIOS INT 05h requests cannot be performed simultaneously from within the same DOS session. The second print screen request is ignored.
 
 
 
 
 
=== Printer Close Processing ===
 
BIOS printer interrupts operate on a single-character basis, which can have a negative impact on printer and system performance. For this reason, the VLPT buffers BIOS print requests. When the buffer becomes full, print requests are sent to the file system to be spooled and printed. The size of the application's print request is rarely an even multiple of the VLPT buffer size. This causes the virtual device driver to provide methods of flushing the remaining characters in its buffer.
 
A virtual parallel port device driver's BIOS INT 17h buffers are flushed in one of four ways:
 
*DOS settings PRINT_TIMEOUT automatic close feature <br />*Ctrl+Alt+Print Screen key sequence (''VDHPrintClose'') <br />*Application termination <br />*DOS session termination
 
 
 
 
 
=== DOS Settings PRINT_SEPARATE_OUTPUT ===
 
The user can set the DOS setting PRINT_SEPARATE_OUTPUT to specify whether or not the virtual parallel port device driver should separate INT 17h output sent to the same device by two different DOS programs that are running in the same DOS session.
 
If set OFF, the VLPT will not open a new data stream each time the Program Segment Prefix (PSP) changes.
 
 
 
 
 
=== PRINT_TIMEOUT ===
 
The user can set the DOS setting PRINT_TIMEOUT to specify the length of time in seconds that the VLPT will wait between occurrences of INT 17h before flushing its buffer. A setting of 0 (zero) specifies to wait indefinitely, that is, to never flush the buffer using the timeout mechanism. The PRINT_TIMEOUT mechanism flushes the buffer and closes the data stream automatically each time the DOS application stops printing by using INT 17h for the time specified.
 
 
 
 
 
=== Ctrl+Alt+Print Screen Key Sequence ===
 
After the DOS application has printed the entire file (issued INT 17h), the virtual parallel port device driver can be alerted to flush the remaining characters in its buffer by pressing '''Control+Alt+Print Screen'''. The virtual keyboard device driver calls ''VDHPrintClose''(an exported virtual parallel port device driver entry point) to alert the virtual parallel port device driver that the key sequence has been pressed, and to flush the buffer. See [[00728.htm|VDHPrintClose]].
 
 
 
 
 
=== Application and DOS Session Termination ===
 
The virtual parallel port device driver is notified when the application terminates or the DOS session is closed, and will flush the remaining characters in its buffer.
 
 
 
 
 
=== Direct I/O Access ===
 
The virtual parallel port device driver, at its initialization, registers an Inter-device Driver Communication (IDC) with the physical parallel port device driver. The VLPT requests exclusive access to the parallel port hardware through the VDD/PDD IDC when a DOS application interfaces directly with the hardware. Data transmitted using the direct I/O access method will bypass the spooler. Completion of exclusive access occurs when the key combination '''Ctrl+Alt+Print Screen'''is pressed, the application is terminated , or the DOS session is terminated.
 
 
 
 
 
=== Share Access ===
 
Share Access is an option of the spooler that enables multiple DOS applications to simultaneously access the parallel port. The option is enabled by selecting the '''Share Access'''checkbox in the Parallel Port Settings dialog box found on the output page of the Print Object Setting Notebook.
 
Once enabled, multiple copies of DOS applications that access security devices attached to the parallel port can be started simultaneously. Use of this option turns OFF the serialization of accesses (the protection mechanism) to the parallel port.
 
One DOS application can overwrite another that is using the parallel port, causing the latter application to fail.
 
 
 
 
 
=== Interrupt-Driven Data Transfers ===
 
The virtual parallel port device driver reflects virtual hardware interrupts to applications executing in a DOS session.
 
 
 
 
 
=== Bidirectional Data Transfers ===
 
The extended mode of the PS/2 personal computer parallel port allows the port to be used as a bidirectional eight-bit parallel interface. This capability is supported by the virtual parallel port device driver when DOS applications directly access the parallel port hardware.
 
 
 
 
 
=== Enabling DOS Print TSRs ===
 
The DOS operating system implements its printing function by passing print requests from its INT 21h interface to the single character BIOS INT 17h interface. Many Terminate-and-Stay-Resident (TSR) DOS applications hook into the INT 17h vector chain to perform additional processing (such as font support, spooling, and character set downloading) before sending the print data to the device attached to the parallel port. They expect all print data to pass through to the INT 17h interface.
 
Since these additional functions are now provided by the OS/2 operating system and since BIOS INT 17h is not performance-sensitive, the operating system passes INT 21h print requests as buffers through the file system to the physical parallel port device driver for transmission instead of sending print requests as single character requests to BIOS INT 17h. The gain, by this approach, is the increased throughput and better utilization of the device attached to the parallel port. The trade-off has been the inability of some DOS TSR applications to perform their print functions.
 
LPTDD.SYS is a DOS device driver that can be installed to convert DOS session INT 21h print requests to INT 17h and thereby enable this class of DOS TSRs. By using the &quot;DEVICE=&quot; statement in the CONFIG.SYS file or the DOS_DEVICE option in DOS Settings, the device driver can perform the INT 17h conversion either in all DOS sessions, or in individual DOS sessions corresponding to the two methods, respectively.
 
 
 
 
 
= Installable Virtual Device Drivers =
 
The following list contains all the installable virtual device drivers included with OS/2:
 
*Virtual ASPI device driver (VASPI)
*Virtual CDROM device driver (VCDROM)
*Virtual COM device driver (VCOM)
*Virtual DOS protect-mode extender device driver (VDPX)
*Virtual DOS protect-mode interface device driver (VDPMI)
*Virtual WIN-OS/2 support device driver (VWIN)
*Virtual expanded memory specification device driver (VEMM)
*Virtual extended memory specification device driver (VXMS)
*Virtual keyboard device driver services
*Virtual Advanced OS/2 Joystick Device Driver
*Virtual mouse device driver (VMOUSE)
*Virtual touch device driver (VTOUCH), discussed in Chapter 5
*Virtual video device drivers (VCGA, VEGA, VMONO, VVGA, VXGA, V8514A), discussed in Chapter 5
 
=== Virtual ASPI Device Driver ===
 
The virtual ASPI device driver (VASPI) enables ASPI support for ASPI applications running in a DOS or WIN-OS/2 session of OS/2. Under DOS, users typically load an ASPI manager that routes all requests directly to the hardware. ASPI drivers, such as ASPIDISK and ASPICD, send requests to the ASPI manager, which then sends the command on to the appropriate device.
 
Under OS/2, applications that wish to send ASPI requests do so by routing the requests to a device manager (OS2ASPI.DMD), which converts them into requests that are recognizable to any SCSI-adapter device driver (ADD).
 
During initialization, VASPI establishes communication with OS2ASPI.DMD. This allows VASPI to route all DOS SCSI requests to OS2ASPI.DMD.
 
 
 
 
 
=== Virtual CDROM Device Driver ===
 
The virtual CDROM device driver (VCDROM) enables data and audio support for CDROM applications running in DOS sessions of OS/2. Under DOS, audio and other IOCtl support is provided through the pass-through function of the CDROM file system driver, MSCDEX* DOS applications build a device driver IOCtl request packet and then send it to MSCDEX to be forwarded to the CDROM device manager for service. The position of VCDROM in the CDROM subsystem is shown in the following figure.
 
<pre class="western">
    /-------------\      /-------------\
    | OS/2 CDROM  |      | DOS CDROM  |
    | Application |      | Application |
    \-------------/      \-------------/
      �        |              |    \-----�----\ INT 21h
/-------------\  |              |        /-------------\
|  MMPM/2    |  |              |        |    DOS    |
|  Subsystem  |  |              |        | File System |
\-------------/  |    INT 2fh  |        \-------------/
      \--------�|    / - - - - + - - - - - - - + - - - - \
                |    |        �              �        |
                |    |  /-------------\ /-------------\  |
                |    |  | OS/2 Virtual| | DOS MSCD001 |  |
                |    |  |Device Driver| |Device Driver|  |
                |    |  \-------------/ \-------------/  |
                |    |        �              �        |
                |    \ - - - - + - - - - - - - + - - - - /
                |              |              |
File System API |�------------------------------/
                �        Virtual Device Helper API
          /-------------\
          | OS/2 CDROM  |
          | File System |
          \-------------/
                � File System Helper API
          /-------------\
          | OS/2 CDROM  |
          | Device Mgr  |
          \-------------/
                | SCSI-2 Commands
                |-------------\
                |            �
                |      /-------------\
                |      |  SCSI-2    |
                |      |  Emulation  |
                |      |    Filter  |
                |      \-------------/
                |            | Vendor-Unique
        /-----------------\    | SCSI-1 Commands
        �                �    �
/-------------\  /-------------\
|  Non-SCSI  |  |  SCSI Bus  |
| Host Adapter|  |  Adapter  |
|Device Driver|  |Device Driver|
\-------------/  \-------------/
        �                �
/-------------\  /-------------\
|  Non-SCSI  |  |    SCSI    |
| Host Adapter|  | Bus Adapter |
\-------------/  \-------------/
        �                �
/-------------\  /-------------\
| CDROM Drive |  | CDROM Drive |
\-------------/  \-------------/</pre>
The virtual CDROM device driver provides two distinct features that are necessary to support DOS CDROM applications. First, this virtual device driver emulates MSCDEX by providing the services that CDROM applications require for installation (for example, the version of MSCDEX, the number of CDROM devices that are present in the system, and the drive letters that correspond to the CDROM devices). A listing of MSCDEX Command Codes is given in the following table:
 
<pre class="western">/-------------------------------------------------------------\
|Command            |Function Description                    |
|--------------------+----------------------------------------|
|00h                |Get Number of CDROM Drive Letters      |
|--------------------+----------------------------------------|
|01h                |Get CDROM Drive Device List            |
|--------------------+----------------------------------------|
|02h                |Get Copyright File Name                |
|--------------------+----------------------------------------|
|03h                |Get Abstract File Name                  |
|--------------------+----------------------------------------|
|04h                |Get Bibliographic File Name            |
|--------------------+----------------------------------------|
|05h                |Read VTOC                              |
|--------------------+----------------------------------------|
|06h                |Reserved                                |
|--------------------+----------------------------------------|
|07h                |Reserved                                |
|--------------------+----------------------------------------|
|08h                |Absolute Disk Read                      |
|--------------------+----------------------------------------|
|09h                |Absolute Disk Write                    |
|--------------------+----------------------------------------|
|0Ah                |Reserved                                |
|--------------------+----------------------------------------|
|0Bh                |CDROM Drive Check                      |
|--------------------+----------------------------------------|
|0Ch                |MSCDEX Version                          |
|--------------------+----------------------------------------|
|0Dh                |Get CDROM Drive Letters                |
|--------------------+----------------------------------------|
|0Eh                |Get/Set Volume Descriptor Preference    |
|--------------------+----------------------------------------|
|0Fh                |Get Directory Entry                    |
|--------------------+----------------------------------------|
|10h                |Send Device Request                    |
|--------------------+----------------------------------------|
|11h - 0FFh          |Reserved                                |
\-------------------------------------------------------------/</pre>
The second, and major, function of the virtual CDROM device driver is to translate the DOS-style IOCtls into requests that the physical CDROM device driver can understand.
 
A comparison of DOS-style IOCtls and OS/2-style IOCtls is given in the following table:
 
 
 
<pre class="western">/--------------------------------------------------------------------------\
|DOS      |          |OS/2      |          |                              |
|----------+----------+----------+----------+------------------------------|
|Category  |Function  |Category  |Function. |IOCtl/Command Description    |
|----------+----------+----------+----------+------------------------------|
|02h      |00h      |***  (7)  |          |Return Address of Device      |
|          |          |          |          |Header                        |
|----------+----------+----------+----------+------------------------------|
|02h      |01h      |80h      |70h      |Return Location of Head      |
|----------+----------+----------+----------+------------------------------|
|02h      |04h      |81h      |60h      |Return Audio-Channel          |
|          |          |          |          |Information                  |
|----------+----------+----------+----------+------------------------------|
|02h      |06h      |80h      |60h      |Return Device Status          |
|----------+----------+----------+----------+------------------------------|
|02h      |07h      |80h      |63h      |Return Sector Size            |
|----------+----------+----------+----------+------------------------------|
|02h      |08h      |80h      |78h      |Return Volume Size            |
|----------+----------+----------+----------+------------------------------|
|02h      |09h      |***  (8)  |          |Return Changed Media Code    |
|----------+----------+----------+----------+------------------------------|
|02h      |0Ah      |81h      |61h      |Return Audio-Disc Information |
|----------+----------+----------+----------+------------------------------|
|02h      |0Bh      |81h      |62h      |Return Audio-Track Information|
|----------+----------+----------+----------+------------------------------|
|02h      |0Ch      |81h      |63h      |Return Audio-Subchannel Q Info|
|----------+----------+----------+----------+------------------------------|
|02h      |0Eh      |80h      |79h      |Return UPC                    |
|----------+----------+----------+----------+------------------------------|
|02h      |15h      |81h      |65h      |Return Audio-Status          |
|          |          |          |          |Information                  |
|----------+----------+----------+----------+------------------------------|
|03h      |00h      |80h      |44h      |Eject Disc                    |
|----------+----------+----------+----------+------------------------------|
|03h      |01h      |80h      |46h      |Lock/Unlock Door              |
|----------+----------+----------+----------+------------------------------|
|03h      |02h      |80h      |40h      |Reset Drive                  |
|----------+----------+----------+----------+------------------------------|
|03h      |03h      |81h      |40h      |Audio-Channel Control        |
|----------+----------+----------+----------+------------------------------|
|          |***  (1)  |80h      |61h      |Identify CDROM Driver        |
|----------+----------+----------+----------+------------------------------|
|          |***  (2)  |80h      |72h        | Read  Long                        |
| ---------- + ---------- + ---------- + ---------- + ---------- ---------- ---------- |
|            | * * *    ( 3 )    | 80h        | 50h        | Seek                              |
| ---------- + ---------- + ---------- + ---------- + ---------- ---------- ---------- |
|            | * * *    ( 4 )    | 81h        | 50h        | Play  Audio                      |
| ---------- + ---------- + ---------- + ---------- + ---------- ---------- ---------- |
|            | * * *    ( 5 )    | 81h        | 51h        | Stop  Audio                      |
| ---------- + ---------- + ---------- + ---------- + ---------- ---------- ---------- |
|            | * * *    ( 6 )    | 81h        | 52h        | Resume  Audio                    |
\ ---------- - ---------- - ---------- - ---------- - ---------- ---------- ---------- / </pre>
'''Note:'''
 
1. Command is not available in DOS.
 
2. DOS Extended Device Driver Command 130h.
 
3. DOS Extended Device Driver Command 131h.
 
4. DOS Extended Device Driver Command 132h.
 
5. DOS Extended Device Driver Command 133h.
 
6.. DOS Extended Device Driver Command 136h.
 
7. Command is not available in OS/2.
 
8. Corresponds to OS/2 block device driver command 01h.
 
The virtual and physical CDROM device driver's provide roughly the same device services, but through different IOCtl interfaces. The DOS CDROM interface is available through the IOCtl input and output device driver request packets, while the physical CDROM device driver provides its services through the generic IOCtl interface. The virtual CDROM device driver maps the DOS IOCtls to their corresponding physical device driver IOCtls, and then passes them on to the physical CDROM device driver. On return from the physical CDROM device driver, the virtual CDROM device driver also maps the return information and the return codes back into the DOS-style environment.
 
The virtual CDROM device driver provides full emulation of MSCDEX. MSCDEX Version 2.21 is fully supported under IBM Operating System/2
 
 
 
 
 
=== Virtual COM Device Driver ===
 
The virtual COM device driver (VCOM) consists of virtual support for the serial communication I/O ports, and for the serial channel-related BIOS entry points. It provides support in each DOS session for up to four COM ports. In addition, this component allows existing DOS applications, which access communications channels by direct access to the I/O ports or by normal BIOS calls, to operate without change.
 
The VCOM only supports access to communication channels that are physically present on a given system. This does not include support for accessing communication devices that can be redirected by network software. From the perspective of the DOS session, the VCOM supports access through:
 
*BIOS <br />*I/O address space
 
 
 
 
 
=== Support Summary ===
 
The VCOM directly supports invocations of BIOS INT 14h, instead of allowing the BIOS to access the ports directly. However, direct access to the virtual I/O ports is also supported. Direct access to I/O ports results in emulation of a communication controller with the INS8250 UART. When referenced through the virtual I/O ports, the VCOM also provides all support for virtual interrupt indication. The hardware appears to the DOS session as a serial interface supported by standard expansion bus serial ports on a PS/2 personal computer.
 
 
 
 
 
=== Interrupt Service ===
 
The virtual COM device driver provides full support for the virtualization of communication channel interrupts, and follows the same logic as the actual hardware.
 
 
 
 
 
=== Virtual DOS Protect-Mode Extender Device Driver ===
 
The virtual DOS protect-mode extender device driver (VDPX) provides address translation from protect mode to V86 mode for DOS protect-mode interface ( DPMI) applications. This translation is necessary because DPMI applications run in protect mode but issue interrupt requests, which can be handled in V86 mode, to perform various system services. When running in protect mode, the application is using selectors instead of segments. Therefore, any data buffers in the protect-mode memory address space (above 1MB) must be copied into a region of memory within the V86 address space.
 
The vdpx registers the DOS setting DPMI_DOS_API, which controls whether the VDPX is active or not. If the user selects:
 
Enabled The VDPX always translates the interrupts it supports from protect mode to V86 mode.
 
Auto The application must first issue the following INT 2Fh in protect mode to begin the translation:
 
 
 
<pre class="western">    ENTRY    AX = 168Ah
              DS:(E)SI points to the ASCIIZ
                  string &quot;MS-DOS&quot;
    EXIT      If VDPX fails initialization:
                  AL = 0x8A</pre>
'''Note:'''MS-DOS is a trademark of Microsoft Corporation.
 
Disabled The VDPX does not perform any address translation.
 
DPMI applications can provide their own translation services. Therefore, it might be unnecessary for the VDPX to perform any address translation.
 
The VDPX translates various interrupts from protect mode to V86 mode, including INT 10h, 15h, 21h, 25h, 26h, 2Ah, 33h, and 5Ch. The VDPX translates most of the commonly-used functions for these interrupts. After the virtual device driver translates the interrupt, the V86-mode interrupt service routine (or the virtual device driver, if it has hooked the interrupt) handles the interrupt request. After issuing the interrupt in V86 mode, the VDPX ensures that any data returned from the V86 service is copied into the data area originally passed in by the DPMI application. The registers and flags returned by the V86-mode handler (other than mode- sensitive registers such as segment registers) are returned to the DPMI application.
 
 
 
 
 
=== Virtual DOS Protect-Mode Interface Device Driver ===
 
The virtual DOS protect-mode interface device driver (VDPMI) provides Version 0.9 DPMI support for applications in a DOS session. DPMI applications run in protect mode instead of V86 mode. The VDPMI provides the necessary support to allow DPMI applications to run under OS/2. The VDPMI supports the DPMI memory limit DOS setting, which allows the user to specify how much protect-mode memory should be available to the DOS session .
 
The VDPMI supports INT 31h in protect mode, which is issued by DPMI applications to request a DPMI service. The VDPMI device driver keeps track of the resources used by the application, such as memory, selector, interrupt, and debug watchpoint management. This virtual device driver also supports the mechanisms necessary to allow DPMI applications to switch the DOS session in and out of V86 mode (translation services). When a DPMI application terminates, the virtual DPMI device driver ensures that all of the DPMI application resources are freed.
 
If a DPMI application issues an interrupt in protect mode and there is no protect-mode interrupt handler, the request is reissued in V86 mode. Most virtual device drivers hook only interrupt requests in V86 mode, so they are not called until the interrupt is reflected to V86 mode unless the virtual device driver has issued ''VDHSetVPMIntVector''. (see [[01066.htm|VDHSetVPMIntVector]]). However, it is up to the application or the virtual DOS protect-mode extender device driver (VDPX) to do any address translation that is necessary, such as converting the selector address to a segment address. See [[00094.htm|Virtual DOS Protect-Mode Extender Device Driver]]for further information on address translation.
 
 
 
 
 
=== DPMI 1.0 Functions Supported ===
 
*401 - Get DPMI Capabilities
 
*504 - Allocate Linear Memory Block
 
*509 - Map Conventional Memory in Memory Block
 
*E00 - Get Coprocessor Status
 
*E01 - Set Coprocessor Status
 
*Separate Local Descriptor Table (LDT) and Interrupt Descriptor Table (IDT) for each protect-mode client
 
 
 
 
 
=== Virtual WIN-OS/2 Support Device Driver ===
 
The virtual WIN-OS/2* support device driver (VWIN) provides interfaces and transport services which enable DOS and OS/2 applications to do communication between processes in a very fast, event-driven, specialized way. The clipboard, DDE and WIN-OS/2 window functions use these interfaces to exchange data between WIN-OS/2 sessions and the Presentation Manager desktop.
 
The data and messages which pass through VWIN are not actually inspected nor understood by the driver. Instead, the driver provides a store and forward mechanism. To accomplish this, an interface is exported for each environment. In an OS/2 session, a thread of the OS/2 process blocks in VWIN waiting for data from any of the other processes. In a DOS session and in a WIN-OS/2 session, the address of a notification routine is registered, and this routine is invoked when a message or data is available from one of the other processes using the interface. Interfaces are provided which allow for sending messages and data to other specific processes or for broadcasting to all processes. This system is outlined in the illustration below:
 
<pre class="western">
          /------------\      /----------------\
          |  OS/2    |      |DOS or WIN-OS/2 |
          |  Process  |      |      Process  |
          \------------/      \----------------/
                �                      �
                |    /------------\    |
                |    |  VWIN    |    |
                \---�|            |�----/
                    \------------/</pre>
 
 
 
 
=== Virtual Expanded Memory Specification Device Driver ===
 
The ''Lotus/Intel/Microsoft Expanded Memory Specification, Version 4.0''(LIM 4 ) provides a standard interface for the use of ''expanded memory''on 8086- family computers. This specification offers up to 32MB of expanded memory divided into as many as 255 expanded memory objects. Regions of these objects can be mapped at 8086 addresses (below 1MB), thus allowing DOS applications access to large memory allocations. However, the memory that is to be accessed must be explicitly mapped.
 
Alternate page tables are provided for quick switches among mappings and function calls with remapping. These tables are also used as the means to save and update mappings, or move and exchange memory contents.
 
The OS/2 virtual expanded memory specification (EMM) device driver:
 
*Implements all the INT 67h functions in the LIM 4.0 EMS, except those for the DMA registers.
 
*Provides each DOS session with a separate EMS emulation. A DOS session has its own set of expanded objects so that features such as interprocess communication work as if each DOS session was running on a different real 80386 DOS sessions cannot affect the availability of objects, or access memory in other DOS sessions.
 
*Provides support for remapping of conventional memory (below 640KB) for use by programs.
 
*Provides a configurable limit for the amount of EMS memory available per DOS session.
 
*Supports multiple physical to single logical mappings. Different 8086 addresses can map to the same expanded memory object address.
 
 
 
 
 
=== Configurable Defaults ===
 
Default values are set for properties in order to be appropriate in most instances. However, users can change these defaults, if desired. The following defaults can be set in the CONFIG.SYS file:
 
Default EMS Memory Size Default limit set by specifying the number of kilobytes of memory desired on a &quot;DEVICE=&quot; line in the CONFIG.SYS file. Alternately, the limit can be specified by using a switch, /S=xxx, on the line. For example:
 
<pre class="western">        DEVICE=path\VEMM.SYS 1024</pre>
or
 
<pre class="western">        DEVICE=path\VEMM.SYS/S=1024</pre>
Default EMS Low OS Map Region Size of remappable conventional memory set by using the /L switch. For example:
 
<pre class="western">        DEVICE=path\VEMM.SYS /L=256</pre>
EMS High OS Map Region Size of extra mappable memory (other than the 64KB minimum) set by using the /H switch. For example:
 
<pre class="western">        DEVICE=path\VEMM.SYS /H=32</pre>
EMS Frame Location Default frame position set by using the /F switch. Any value in the DOS setting list can be chosen as the default. For example:
 
<pre class="western">        DEVICE=path\VEMM.SYS /F=AUTO</pre>
or
 
<pre class="western">        DEVICE=path\VEMM.SYS/F=C800</pre>
 
 
When devices without virtual device drivers can directly map memory, the Include and Exclude regions are crucial for the virtual EMM device driver. These properties are supplied by another component, and determine which regions can be directly mapped to physical addresses by default when touched by applications.
 
The virtual DevHlp Mapping services allow the same master page to be aliased in by successive pages in the V86 address space. In particular, EMM allows an application to map in the same 16KB size range of memory repeatedly (for example, a 64KB page frame could consist of the same four pages mapped four times). Since DMA requires contiguous physical memory, I/ O that involves aliased pages, which map to the same physical page, must be handled by breaking up DMA requests.
 
 
 
 
 
=== Virtual Extended Memory Specification Device Driver ===
 
The ''Extended Memory Specification, Version 2''provides a standard interface for the use of ''extended memory''on 80286- and 80386-based machines. The XMS specifications manage three distinct regions of memory:
 
*High Memory Area (HMA). Extended memory accessible from real mode by enabling the A20 address line. Code can be executed in the HMA, if the A20 line is enabled. The high memory area is exactly 65520 bytes (64KB-16 bytes ) long.
 
*Extended Memory Blocks (EMBs). Blocks of extended memory accessible by way of XMM function calls through a handle. Without leaving V86 mode, code cannot be executed from EMBs; they serve only for data storage. The specification offers up to 64MB of extended memory divided into as many as 255 blocks.
 
*Upper Memory Blocks (UMBs). Block of memory located between 640KB and 1MB. Once a UMB is allocated, its memory is always available. Since the memory lies in conventional memory, code can be executed in it at any time.
 
The virtual extended memory specification (XMS) device driver:
 
*Implements all the functions in XMS 2.0.
 
*Provides each DOS session with a separate XMS emulation. Each DOS session has its own high memory area, upper memory blocks, and extended memory blocks so that features such as interprocess communication perform as if each DOS session was running on a different real 80386. A DOS session cannot affect the availability of objects, or access memory in another DOS session.
 
*Provides configurable limits for the amount of XMM memory available across DOS sessions, and a limit per DOS session. An installed program in the start list should be able to override the per-DOS session limit, subject to the constraint given by the overall limit. In addition, it should be able to disable XMS completely for a particular DOS session, if its installation would conflict with the program running in the DOS session.
 
A CONFIG.SYS line of the form DEVICE=path\VXMS.SYS [options], will interpret ''options''as ''&quot;/keyword=value&quot;''. These options are as follows:
 
/XMMLIMIT=g,i Set the global (system-wide) maximum memory usage of the virtual XMS device driver to ''g''KB, and set a per-DOS session maximum of ''i''KB. These values are large enough to accommodate an automatic 64KB allocation in each DOS session for the HMA. Values are restricted to the range 0 through 65535 (=64KB).
 
The values of ''g''and ''i''are rounded up to the nearest multiple of four. Specifying i=0 suppresses XMS installation in all DOS sessions unless overridden by a DOS session-specific configuration string. The default for /XMMLIMIT is 16384,2048.
 
/HMAMIN=d Set the minimum request size (in kilobytes) for an HMA request to succeed. Values are restricted to the range 0 through 63. The default for / HMAMIN is 0.
 
/NUMHANDLES=n Set the number of handles available in each DOS session. Each handle occupies eight bytes. Values are restricted to the range 0 through 128. The default for /NUMHANDLES is 32.
 
/UMB Instruct XMM to create Upper Memory Blocks (UMB). The default is / NOUMB.
 
/NOUMB Instruct XMM to not create Upper Memory Blocks (UMB). The default is /NOUMB.
 
 
 
 
 
=== Virtual Keyboard Device Driver Services ===
 
The virtual video device driver utilizes the Post Peek and Post Read requests from the virtual keyboard device driver to post events to the DOS session Window Manager when the windowed DOS session video state changes. In addition to generating the VVDEVENT_INPUT event to the DOS session Window Manager to adjust window orientation, these notifications also serve to suggest to the virtual video device driver when to check for palette and LVB changes, which generate VVDEVENT_PALETTE and VVDEVENT_LVB events.
 
The virtual keyboard device driver uses the Post Paste request to indicate whether paste operations can start or end. The virtual video device driver posts the VVDEVENT_PASTE or VVDEVENT_ENDPASTE event to the DOS session Window Manager, based on the type of paste operation requested.
 
 
 
 
 
=== Virtual Advanced OS/2 Joystick Device Driver ===
 
The virtual joystick device driver has two main purposes:
 
*To provide a reliable joystick device driver for DOS games running under OS/2.
 
*To provide a standard device driver for OS/2 game programmers that they can use as an interface between the PC game adapter port and their products .
 
See the ''OS/2 Input/Output Device Driver Reference''for detailed information on understanding how the IBM PC Game-Port Adapter works and using the Advanced OS/2 Joystick Device Driver.
 
 
 
 
 
=== Understanding How the Joystick Device Driver Works ===
 
The pre-emptive multi-tasking nature of OS/2 can cause DOS applications reading the game adapter port to deduce incorrect positions for the joysticks connected. The solution to this potential inaccuracy, implemented in the joystick device driver, is to regularly sample the game adapter port inside the Physical Device Driver (PDD) and then return fabricated values to the DOS application that reflect that state. With the logic for regular sampling already in the PDD, it is simply a matter of activating the procedure.
 
Before any of this can be initiated, however, access to the game port by the DOS application must first be trapped. Whenever I/O ports are to be trapped or emulated, an OS/2 Virtual Device Driver (VDD) is required. The VDD works in conjunction with the PDD to provide the device emulation. The VDD does this by capturing port reads and returning values that reflect the current state as determined by the PDD. The VDD is also responsible for determining whether a given virtual DOS machine (VDM) is to have direct access to the port and, if it is, for obtaining ownership of the VDM.
 
 
 
 
 
=== Virtual Mouse Device Driver ===
 
The virtual mouse device driver (VMOUSE) is responsible for all mouse support in the multiple DOS session environment.
 
 
 
 
 
=Virtual Mouse Device Driver =
 
This chapter describes the virtual mouse device driver (VMOUSE), which is responsible for all mouse support in multiple DOS sessions. The virtual mouse device driver also supports applications that use the BIOS INT 15h ( AH = C2h) pointing-device services.
 
Some of the most common mouse driver services, available through the INT 33h interface, are listed below:
 
*Driver-state save, restore, and disable <br />*Light-pen emulation <br />*Miscellaneous features <br />*Position and button-event notification <br />*Position and button-data tracking <br />*Selectable pel-to-coordinate and mickey-to-pel mappings <br />*Video-mode tracking <br />*Video pointer management (location and appearance)
 
There are no restrictions on any use of the INT 33h interface, even when a DOS session is in background mode. The only difference between background, focused, and foreground DOS session support is that no mouse events are posted for a background DOS session. Mouse events are posted to full-screen DOS session from the physical mouse device driver, and are posted through the Presentation Manager shield to focused, windowed DOS sessions. The pointer position should remain unchanged as long as a DOS session is in background mode, unless an application initiates pointer movement of its own. In that case, the virtual pointer position changes but nothing is drawn (not even in virtual video space).
 
The virtual mouse device driver also supports applications that use the BIOS INT 15h (AH=C2h) Pointing Device services.
 
=== INT 33h Support ===
 
INT 33h support is provided directly by the virtual mouse device driver. If a DOS session is running in a window (instead of full screen), and is in focus, the physical mouse device driver routes the mouse events to the Presentation Manager single queue device driver, then to the shield, and eventually to the virtual mouse device driver. The virtual mouse device driver then buffers the mouse event as if it were for the full-screen DOS session. When the DOS setting MOUSE_EXCLUSIVE_ACCESS is ON for a windowed DOS session, all mouse events go directly from the physical mouse device driver to the virtual mouse device driver, bypassing the Presentation Manager interface. This property is necessary for those applications that track and draw their own mouse pointer.
 
 
 
 
 
=== Driver-State Save, Restore, and Disable ===
 
Services are provided to copy all per-DOS session mouse-state information to an application-defined block and back again. When the driver is disabled , it ignores all INT 33h requests and physical mouse device driver events.
 
 
 
 
 
=== Light-Pen Emulation ===
 
Whenever this INT 33h feature is enabled, a virtual mouse device driver INT 10h hook is established, and INT 10h light-pen functions are emulated with mouse position and button data.
 
 
 
 
 
=== Miscellaneous Features ===
 
The INT 33h interface provides a function to read-and-reset ''mouse motion counters'', which are simply software counters of total horizontal and vertical mickeys. These counters are simulated within the virtual mouse device driver by taking reported pel movements and converting them to mickeys (based on the current mickey-to-pel ratio). This interface must also provide counts of button presses and releases, and the positions at the time of the last press and release. These are maintained by the virtual mouse device driver without any assistance from the physical mouse device driver.
 
 
 
 
 
=== Position and Button-Event Notification ===
 
The INT 33h interface provides services to allow the DOS session to receive call-back notification for selectable motion and button events. These call- backs occur at DOS session task time, and do not involve the physical mouse device driver.
 
Each time the DOS session is notified of a mouse event, it might have to notify the DOS session's user-defined mouse-event subroutine, depending on whether the DOS session's application has registered the subroutine (by way of an INT 33h function) and what events the caller has asked to be notified of.
 
A registered subroutine is called by requesting a ''pseudo''interrupt in the DOS session. A simulated interrupt service routine (loaded into each DOS session at creation) immediately ''EOI''s (ends the interrupt) and then proceeds to notify the DOS session's registered subroutine. In order to pick an IRQ that is guaranteed not to conflict with any other virtual device driver, the DOS session queries the physical mouse device driver at initialization for its physical IRQ.
 
'''Note:'''It is not important to have the real mouse IRQ, but simply an IRQ that no other virtual device driver needs.
 
Movement-only events are coalesced. As an event is posted from the physical mouse device driver, the DOS session compares it with any previous event in the event buffer; if it is a movement-only event, the current event accumulates with the previous event in the buffer. This process continues until a non-movement-only event occurs or the current movement event is simulated, thus reducing interrupt-simulation overhead during rapid event- generation periods.
 
 
 
 
 
=== Position and Button-Data Tracking ===
 
Other services within the INT 33h interface allow the DOS session to poll the virtual mouse device driver on the current mouse status. There are also services to return the last button press and also the last button-release event.
 
 
 
 
 
=== Selectable Pel-to-Coordinate and Mickey-to-Pel Mapping ===
 
Through the INT 33h interface, the DOS session can control the acceleration of the DOS session mouse pointer by varying both the thresholds and the multipliers. This is managed by the entirely by the virtual mouse device driver, without assistance from the physical mouse device driver, which reports only raw mickey events to the DOS session for full-screen DOS sessions.
 
For windowed DOS sessions, the PM Shield reports absolute pel mouse events to the virtual mouse device driver The virtual mouse device driver maps the raw delta mickeys to the DOS session's current virtual-coordinate grid.
 
 
 
 
 
=== Video Mode Tracking ===
 
The virtual mouse device driver receives notification of video mode changes from the virtual video device driver, so that the pointer size and bounds can be appropriately set.
 
The virtual mouse device driver must be notified of changes in the physical dimensions of the screen. It uses that information to map the raw mickeys into pel coordinates. The virtual device driver uses a device-independent interface to notify the virtual mouse device driver of mode changes so that the virtual mouse driver is capable of supporting any video device without code changes.
 
 
 
 
 
=== Video Pointer Management ===
 
The virtual mouse device driver tracks the pointer location, and whether or not the pointer is visible. The actual drawing and hiding of the pointer, however, is handled by the virtual video device driver.
 
Interfaces are provided by the virtual video device driver to the virtual mouse device driver to perform the following operations:
 
Define pointer This describes the desired pointer shape and always is issued prior to making a pointer visible for the first time. An error might be returned if the virtual video device driver does not provide pointer support for the current video mode, thus permitting the virtual mouse device driver to skip further drawing and moving requests. The virtual video device driver refuses calls it cannot support.
 
Draw pointer A position, in pel coordinates, is provided. For text modes, the virtual video device driver maps ''chunks''of pels to individual character locations. The size of a chunk is 8 pels x 8 pels, unless the mode is 40- column, in which case the chunk size is 16 pels x 8 pels. A video page parameter is provided to support the INT 33h SetCRTPage service. Draw requests without intervening Remove requests are treated as Move requests.
 
Remove pointer Deletes pointer from the screen.
 
 
 
 
 
=== INT 15h (AH=C2h) Support ===
 
All the published Pointing Device BIOS services (INT 15h, AH=C2H) are emulated in the virtual mouse device driver For a complete listing of these services, refer to the ''IBM Personal System/2 and Personal Computer BIOS Interface Technical Reference''.
 
 
 
 
 
=== Virtual Mouse Device Driver Services ===
 
For the virtual mouse device driver, the virtual video device driver provides a ''VDHRequestVDD''function, as well as several direct interfaces for pointer drawing operations. The following ''VDHRequestVDD''service is provided :
 
 
 
<pre class="western">  VDHRequestVDD
  (
      HVDD  hvddVideo,
      HVDM  hvdm,
      INT  iFunc,      /* Virtual video device driver EVREQ_POSTMOUSE (4)  */
      PVOID pReqIn,      /* Undefined.                                        */
      PVOID pReqOut      /* Undefined.                                        */
  );                    /* Returns TRUE.                                    */</pre>
The virtual mouse device driver must return the address of a function that permits the virtual video device driver to obtain mouse position and button status during processing of the INT 10h, Query Light Pen function, when light pen emulation is enabled for the active DOS session. Also, whenever the DOS session changes video modes (including the initial mode change that takes place during DOS session creation), the virtual video device driver notifies the virtual mouse device driver of the new mode and screen dimensions.
 
 
 
 
 
=== Virtual Touch Device Driver ===
 
The virtual touch device driver (VTOUCH) provides support for the INT 7Fh in multiple DOS sessions. This virtual device driver is limited (by default ) to making actual touch XYZ data available only to full-screen DOS programs because the physical device driver, which handles the touch data interrupts, cannot determine which window to send the touch data to when running with the Presentation Manager session in the foreground.
 
In contrast, the physical mouse device driver can determine which window to send the mouse data to because it is able to feed the single queue of the Presentation Manager. The Presentation Manager can then determine, based upon the event XYZ data, which window is to receive the event. If the window is a DOS window, it calls the virtual device driver.
 
For those DOS applications that receive full screen XYZ touch data while running in a window, the DOS setting TOUCH_EXCLUSIVE_ACCESS is provided. This DOS setting effectively turns off mouse emulation and directs all touch data to that window. The (now device-independent) INT 7Fh continues to function in a window. However, touch data is not available to the application until it is switched to full screen. In all other respects, the application functions exactly as before.
 
DOS mouse applications are not subject to this restriction because they can run in a windowed or full screen DOS session with touch input in the form of emulated mouse data.
 
 
 
 
 
=== INT 7Fh Support ===
 
To access the touch-sensitive display device, DOS applications use the software interrupt 7Fh (INT 7Fh) interface. OS/2 applications use the Tou ''xxx''API. The virtual touch-sensitive device driver provides this by using a standard DOS session software interrupt hook. This virtual device driver runs in protect mode (which allows it to share code in all DOS sessions) and virtualizes all the hardware-dependent features that the INT 7Fh interface provides (for example, changing thresholds).
 
In addition to the touch-sensitive device capability, it is also possible to use the touch-sensitive display to emulate the IBM* mouse. In this case, the standard mouse INT 33h API (for DOS) is used.
 
Note that only DOS sessions running full screen can obtain full touch XYZ data. Windowed DOS sessions running under Presentation Manager are restricted to emulated mouse data. A DOS touch application that started as full screen stops receiving touch data if it is switched to a window, and starts receiving data again if it switched back to full screen. Conversely, a DOS touch application that is started in a window does not receive data until it is switched to full screen, and does not stop receiving data until it is switched back to a window.
 
 
 
 
 
=== Discussion ===
 
A virtual video device driver is used by OS/2 as a virtual display device for DOS applications executing in a DOS session, by providing virtual hardware support. Virtual video device drivers are required when it is necessary for multiple DOS sessions to share one or more video devices.
 
The virtual video device driver manages access to video memory, video registers, and video adapter ROM BIOS Special functions have been defined to permit other OS/2 Ring 3 components (such as the DOS Session Manager and the Presentation Manager display device driver) to obtain the vital video state information necessary to window a DOS session on the Presentation Manager desktop.
 
For simplicity, a dedicated virtual video device driver should be targeted to a specific video device. This reference manual includes a set of virtual video device drivers that can be used as templates for enhancement modifications to any of the currently supported devices, or they can be used as samples to create a virtual device driver ''from scratch''for a similar but compatible device. For example, the OS/2 virtual Super VGA device driver (VSVGA.SYS) is a derivative of the virtual VGA device driver (VVGA.SYS).
 
The following virtual video device drivers, which cover an extensive range of the most commonly used video devices, are included in this reference manual:
 
<pre class="western">/-----------------------------------------\
|Virtual CGA device driver|VCGA          |
|-------------------------+---------------|
|Virtual EGA device driver|VEGA          |
|-------------------------+---------------|
|Virtual MONO device      |VMONO          |
|driver                  |              |
|-------------------------+---------------|
|Virtual VGA device driver|VVGA          |
|-------------------------+---------------|
|Virtual XGA* device      |VXGA          |
|driver                  |              |
|-------------------------+---------------|
|Virtual SVGA device      |SVGA          |
|driver                  |              |
|-------------------------+---------------|
|Virtual 8514/A device    |V8514A        |
|driver                  |              |
\-----------------------------------------/</pre>
The video devices for which the OS/2 provides virtual video device drivers include:
 
*Western Digital** <br />*ATI** <br />*Cirrus Logic** <br />*Headland Technology** <br />*Trident** . <br />*Tseng** <br />*Video 7**
 
'''Note:'''Specific Super VGA chip revision and model support can be found in VVDP.H.
 
 
 
 
 
=== Installable Virtual Video Device Driver Architecture ===
 
The architecture of a virtual video device driver adheres to the architecture defined for all virtual device drivers. However, some parts of the multiple DOS sessions architecture have been designed primarily for virtual video device drivers, as follows:
 
*Foreground and background ''notification hooks''<br />*''Freeze''and ''thaw''services <br />*Title change and code-page change notification hooks
 
A significant amount of the primary virtual video device driver code involves communication with the DOS session Window Manager. A Remote Procedure Call (RPC) mechanism must be used to communicate between the DOS session Window Manager and a virtual video device driver under the following conditions:
 
*The DOS session Window Manager is a Ring 3 component (lowest privilege level) <br />*Virtual device drivers run at Ring 0 (highest privilege level) <br />*DOS sessions have no Local Descriptor Table (LDT), and therefore cannot attach to Dynamic Link Libraries (DLLs)
 
For this purpose the DOS session Window Manager creates a thread that calls the virtual video device driver to wait for a video event from any of the currently windowed DOS sessions.
 
 
 
 
 
=== Design of Installable Virtual Video Device Drivers ===
 
A virtual video device driver is a ''base''device driver, although a &quot;DEVICE=&quot; statement in the CONFIG.SYS file is used to specify one or more virtual video device drivers to load. The DOS session Manager and DOS session Window Manager identify a virtual video device driver by its registered name. For example, a virtual video device driver for the primary display would register as VVIDEO1$, a virtual video device driver for the secondary display device would register as VVIDEO2$, and so forth.
 
'''Note:'''Support of multiple DOS sessions is disabled if no virtual video device driver claims ownership of the primary display device after virtual video device driver loading and initialization is completed.
 
 
 
 
 
=== Supporting DOS-Standard Adapters and Modes ===
 
IBM-compatible CGA, EGA, VGA, XGA, and 8514/A adapters are supported as primary display devices; monochrome adapters are supported as secondary display devices. For these devices, the standard configurations (including the amount of video memory, type of monitor and so forth), are supported. However, there are a few exceptions. For example, other dual-adapter combinations such as EGA/monochrome with CGA/color, or VGA/monochrome with CGA/color are not supported.
 
All EGA monitor combinations (RGB, ECD, and monochrome) and VGA, XGA, 8514/ A monitor combinations (i512/8513, 8514, and 8515), as well as all EGA memory combinations (64KB, 128KB, 192KB, and 256KB) of the 8514/A monitor are supported. The type of monitor used with a monochrome or CGA adapter is immaterial; that is, the behavior of the adapter is not affected.
 
There are some limitations, however. For example, an EGA, VGA, or Super VGA with a 2''xx''port configuration, instead of the standard 3''xx''configuration, is not supported. Also, an EGA display with only 64KB of display memory cannot support high-resolution graphic modes in a window, due in part to the video mode used concurrently by Presentation Manager (640 x 200, 16 colors), which consumes nearly all of the 64KB of on-board video memory. In addition, blinking attributes (whether in text or graphics modes) cannot be emulated in a DOS window.
 
A significant portion of the primary virtual video device drivers involves communication with the DOS session Window Manager. This includes providing a set of services to fully describe a DOS session's video state and a set of notifications to signal when the video state changes, so that a DOS session being windowed remains relatively synchronized with its associated DOS session that is executing in the background.
 
Because the DOS session Window Manager, OS/2 Session Manager, and Presentation Manager display device driver execute in Ring 3, and while the virtual video device driver runs in Ring 0, a system entry point is necessary for these Ring 3 components to communicate with the virtual video device driver. The virtual video device driver provides the following ''DosRequestVDD''service to:
 
*DOS session Window Manager <br />-Set Access <br />-Set Focus <br />-Set Lock <br />-Query Mode Info <br />-Query Cursor Info <br />-Query Palette Info <br />-Copy LVB Content <br />-Copy Bit Map Content <br />-Wait for Video Event <br />-Control Event <br />*PM Display Device Driver <br />-Set Display Requirements <br />-Request off-screen VRAM <br />-Free off-screen VRAM <br />-Request VGA Controller <br />-Free VGA Controller <br />-Query VRAM Status
 
'''Note:'''See the ''Display Device Driver Reference''for a detailed explanation of the ''DosRequestVDD''functions provided by the virtual video device driver.
 
There are two kinds of DOS session window support:
 
*Displaying a running image in a window <br />*Displaying a frozen image in a window
 
The latter is a subset of the former. The virtual video device driver always attempts to provide support for displaying a running image and for standard text and CGA graphics modes this is always possible, but there are graphics modes cases where that is not possible. One example is the 64KB EGA mode; other examples are the XGA and 8514/A modes.
 
Support for the XGA or 8514/A graphics modes is not a matter of sufficient memory but of the sheer complexity of virtualizing the 8514/A hardware. In addition, if a DOS application uses VGA graphics modes on an 8514/A system, it will not be able to use the VGA memory if a monitor being used as a secondary display by other tasks in the system is connected to the VGA.
 
There is no known, reliable method of determining whether a monitor is connected to the VGA or Super VGA. The 8514/A can detect a limited set of IBM-compatible, fixed-frequency monitors whereas the XGA, using DMQS, has the potential of identifying all monitor types, including OEMs.
 
In an 8514/A system, there is no architected way for the virtual video device driver to determine whether the VGA is in use by another process or session. Conversely, there is no way for the virtual video device driver to claim the device and prevent other processes or sessions from later acquiring the device.
 
'''Notes:'''
 
1.256-color modes will not be accurately rendered in a window even when the PM display driver supports 256 colors, because the DOS session Window Manager does not provide Palette Manager support.
 
2.High-resolution graphics modes on a 64KB EGA currently will not be rendered properly in a DOS window because the memory organization is substantially different (planes 0 and 1 and planes 2 and 3 are chained together).
 
OS/2 provides a single, generic Super VGA virtual device driver that supports the majority of the Super VGA video adapters made with the above- mentioned Super VGA chip sets. However, there are a small number of adapters that cannot be reliably virtualized, due to the way they are designed. For example, adapters that require multiple OUTs to a specific port before permitting the extended clock bits to be programmed fall into that category.
 
Of the 8514/A graphics modes, only the 1024 x 768 256-color mode has been tested for accurate rendering in a window.
 
 
 
 
 
=== Virtual Video Device Drivers ===
 
The following list contains the installable virtual video device drivers that are included with the ''Developer's Tooklkit for OS/2:''
 
*Virtual CGA device driver (VCGA) <br />*Virtual EGA device driver (VEGA) <br />*Virtual MONO device driver (VMONO) <br />*Virtual VGA device driver (VVGA) <br />*Virtual XGA device driver (VXGA) <br />*Virtual 8514/A device driver (V8514A)
 
The architecture of the virtual video device driver adheres to the architecture defined for all virtual device drivers. However, some portions of the multiple DOS session architecture have been designed primarily for ( or used by) virtual video device drivers:
 
*Foreground and background notification hooks <br />*Freeze and thaw services <br />*Title change and code-page change notification hooks
 
A significant portion of the primary display virtual device drivers involves communication with the DOS session Window Manager. This includes providing a set of services to fully describe a DOS session's video state and a set of notifications to signal selected changes in state, so that a window remains relatively synchronized with its associated DOS session.
 
 
 
 
 
=== Discussion ===
 
Because the DOS session Window Manager is a Ring 3 component, virtual device drivers run at Ring 0, and DOS sessions have no LDT (and therefore cannot attach to DLLs), a Remote Procedure Call (RPC) mechanism must be used to communicate between the DOS session Window Manager and a virtual device driver. The DOS session Window Manager creates a thread for this purpose, which calls the virtual video device driver to wait for a video event from any of the currently windowed DOS sessions.
 
Virtual video device drivers are base device drivers. &quot;DEVICE=&quot; statements in the CONFIG.SYS files are used to specify one or more virtual video device drivers to load. The DOS session Manager and DOS session Window Manager identify a virtual video device driver by its registered name (for example, a virtual video device driver for the primary display device would register as VVIDEO1$, one for the secondary display device would register as VVIDEO2$, and so forth). After virtual video device driver loading and initialization is complete, if no virtual device driver has registered for the primary display device, multiple DOS session support is disabled.
 
IBM-compatible CGA, EGA, VGA, XGA, and 8514/A adapters are supported as primary display devices, and MONO adapters are supported as secondary display devices. For these devices, all the standard configurations (that is, amount of video memory, type of monitor, and so forth) are supported. However, there are a a few exceptions. For example, support for other dual- adapter combinations, such as EGA/monochrome with CGA/color, or VGA/ monochrome with CGA/color, are not specifically supported. In addition, all EGA monitor combinations (RGB, ECD, and monochrome), EGA memory combinations (64KB, 128KB, 192KB, and 256KB), VGA and 8514/A monitor combinations (8512, 8513, and 8514), and VGA and XGA monitor combinations ( 8512, 8513, 8514, and 8515) are supported. The type of monitor used with a monochrome or CGA adapter does not affect the behavior of the adapter.
 
 
 
 
 
=== Virtual and Nonvirtual Operation ===
 
For optimal performance and compatibility, the virtual video device drivers support full-screen operation. In this mode, there is no visual difference between DOS and DOS session operation. For convenience, an option appears on the DOS session system menu to convert the DOS session from windowed mode to full-screen mode and back. Virtual video device drivers support full-screen operation by performing the following operations:
 
*Registering foreground and background VIDEO_SWITCH_NOTIFICATION hooks with the DOS session Manager <br />*Allocating a save and restore video buffer <br />*Installing I/O hooks to shadow key video port accesses <br />*Mapping physical video memory into the appropriate video address space <br />*Compelling text-mode fonts to match the currently selected code page <br />*Providing pointer drawing services to the virtual mouse device driver to define, draw, and erase pointer images
 
When a DOS session does not own the physical display (that is, when it is background), the virtual video device drivers:
 
*Install I/O hooks to track and emulate all video port accesses. <br />*Map appropriate system memory to the active portions of the video address space. <br />*Report video events to the DOS session Window Manager (assuming the Presentation Manager is active and the DOS session is an unminimized window ). This includes changes to:
 
<br />-Mode <br />-Palette <br />-Cursor <br />-Video memory <br />-Input events <br />-Scroll or string events <br />-Paste continue or terminate (through the virtual keyboard device driver) <br />-Session title change <br />-Screen-switch or video memory allocation errors
 
At any time, the DOS session Window Manager (or other processes that have access to a DOS session's process ID) can update a DOS session's window state:
 
*Windowed or nonwindowed <br />*Focus or nonfocus <br />*Minimized or unminimized <br />*Lock or unlocked
 
as well as query any aspect of a DOS session's video state:
 
*Mode <br />*Palette <br />*Cursor <br />*Video memory <br />*Wait for video events <br />*Cancel wait for video event
 
 
 
 
 
=== Mouse-Independent Pointer Drawing Services ===
 
When the virtual video device driver creates a DOS session for the first time, it opens the virtual mouse device driver. If the open is successful, it provides the virtual mouse device driver with the following entry points :
 
*Show Pointer <br />*Hide Pointer <br />*Define Text Pointer <br />*Define Graphics Pointer <br />*Set Video Page <br />*Set Light-Pen Emulation
 
Also, whenever the DOS session changes video modes (including the initial mode change that takes place during DOS session creation), the virtual video device driver notifies the virtual mouse device driver of the new mode, the screen dimensions, and so forth.
 
 
 
 
 
=== Built-in Extended INT 10h and INT 2Fh Services ===
 
The EGA register interface is integrated into the virtual video device driver as part of its INT 10h interception logic. This interface is a set of INT 10h services that are used by applications to make drawing operations and simultaneous use of the mouse pointer possible on EGA and VGA hardware. The virtual video device driver's pointer drawing services are intended to replace this interface, but existing graphical applications still use it (generally when mouse support is also present), so the interface must be present or these applications will not function correctly .
 
The INT 2Fh services notify applications when they are about to be switched to full-screen or background mode. Applications can use this notification to stop accessing video memory, if they are using a video memory not supported for background operation. This will prevent them from freezing, and also redraw their screen in the event the virtual video device driver fails to fully restore it.
 
 
 
 
 
=== Summary of the 8514/A and XGA Virtual Device Drivers ===
 
DOS applications currently written to the 8514/A Adapter Interface (AI), the XGA AI, or directly to the 8514/A and XGA display adapters are able to run in a full-screen DOS session. This is due to the ability of each adapter's virtual device driver to:
 
*Grant I/O privilege <br />*Save or restore the video state <br />*Provide video bitmap images to the shield layer when the DOS session is being windowed
 
A DOS application is allowed to run only in a full-screen foreground DOS session, and is immediately frozen if it attempts to access the hardware when switched to the background.
 
The virtual 8514/A device driver statements, which are required in the CONFIG.SYS file, are added during installation when the presence of an 8514 /A display adapter is noted:
 
<pre class="western">        DEVICE=C:\OS2\MDOS\VVGA.SYS
        DEVICE=C:\OS2\MDOS\V8514A.SYS</pre>
The virtual XGA device driver statements, which are required in the CONFIG. SYS file, are added during installation when the presence of an XGA display adapter is noted:
 
<pre class="western">        DEVICE=C:\OS2\MDOS\VVGA.SYS
        DEVICE=C:\OS2\MDOS\VXGA.SYS</pre>
The following items should be set in DOS to enable a DOS session:
 
*Enable I/O trapping to permit the virtual video device driver to save and restore the hardware instance used by a DOS application when the application switches away from the foreground DOS session. The virtual video device driver allocates a buffer to save the video image. The maximum size of this buffer is 1MB and is obtained each time a full-screen DOS session is created.
 
Enabling I/O trapping is the default. Although multiple instances of XGA can be present on a system, the virtual XGA device driver saves or restores only the state of the first instance used by a DOS application. It is the application's responsibility to save or restore the other XGA instances.
 
*Register for screen switch notification. This implies that a DOS application has hooked INT 2Fh so as to be notified when it is to be switched to full-screen foreground or background. This notification informs the application that it must restore the screen when switched to full- screen foreground, and must stop accessing video memory (to avoid freezing) when switched to background.
 
An application that uses more than one instance of XGA must specify this option to save and restore the states of the other XGA adapters. The default is no VIDEO_SWITCH_NOTIFICATION.
 
Any DOS session that is not saved or restored by the virtual video device driver cannot be displayed in a window. DOS 8514/A and XGA applications are not interactive in a window; they can only be viewed.
 
 
 
 
 
=C Language Virtual DevHlp Services =
 
Virtual DevHlp functions are used by virtual device drivers to access various services provided by the OS/2 operating system and by other virtual device drivers. These functions are provided because normal OS/2 API calls from a virtual device driver and routines in a C-language run-time library cannot be used for access purposes.
 
The virtual DevHlp services are categorized in the following list and subsequent sections. Individual functions follow and are listed alphabetically with an explanation of their purpose, parameters, and calling conventions.
 
Function Type <br />[[00152.htm|VDHAllocBlock]]byte-granular memory management service <br />[[00159.htm|VDHAllocDMABuffer]]DMA service <br />[[00168.htm|VDHAllocDOSMem]]byte-granular memory management service <br />[[00175.htm|VDHAllocHook]]hook management service <br />[[00184.htm|VDHAllocMem]]byte-granular memory management service <br />[[00192.htm|VDHAllocPages]]page-granular memory management service <br />[[00201.htm|VDHArmBPHook]]hook management service <br />[[00208.htm|VDHArmContextHook]]hook management service <br />[[00216.htm|VDHArmReturnHook]]hook management service <br />[[00224.htm|VDHArmSTIHook]]hook management service <br />[[00232.htm|VDHArmTimerHook]]timer service <br />[[00241.htm|VDHArmVPMBPHook]]DPMI service <br />[[00248.htm|VDHBeginUseVPMStack]]DPMI service <br />[[00255.htm|VDHCallOutDMA]]DMA service <br />[[00262.htm|VDHChangeVPMIF]]DPMI service <br />[[00269.htm|VDHCheckPagePerm]]DPMI service <br />[[00279.htm|VDHCheckVPMIntVector]]DPMI service <br />[[00286.htm|VDHClearVIRR]]Virtual interrupt service <br />[[00294.htm|VDHClose]]file or device I/O service <br />[[00301.htm|VDHCloseVDD]]inter-device communication service <br />[[00308.htm|VDHCloseVIRQ]]Virtual interrupt service <br />[[00315.htm|VDHCopyMem]]byte-granular memory management service <br />[[00324.htm|VDHCreateBlockPool]]byte-granular memory management service <br />[[00332.htm|VDHCreateSel]]GDT selector service <br />[[00340.htm|VDHCreateSem]]semaphore service <br />[[00348.htm|VDHDecodeProperty]]DOS settings service <br />[[00358.htm|VDHDestroyBlockPool]]byte-granular memory management service <br />[[00365.htm|VDHDestroySel]]GDT selector service <br />[[00372.htm|VDHDestroySem]]semaphore service <br />[[00379.htm|VDHDevBeep]]miscellaneous virtual DevHlp service <br />[[00387.htm|VDHDevIOCtl]]file or device I/O service <br />[[00402.htm|VDHDisarmTimerHook]]timer service <br />[[00409.htm|VDHEndUseVPMStack]]DPMI service <br />[[00416.htm|VDHEnumerateVDMs]]miscellaneous virtual DevHlp service <br />[[00424.htm|VDHExchangeMem]]byte-granular memory management service <br />[[00433.htm|VDHFindFreePages]]page-granular memory management service <br />[[00441.htm|VDHFreeBlock]]byte-granular memory management service <br />[[00449.htm|VDHFreeDMABuffer]]DMA service <br />[[00456.htm|VDHFreeHook]]hook management service <br />[[00463.htm|VDHFreeMem]]byte-granular memory management service <br />[[00470.htm|VDHFreePages]]page-granular memory management service <br />[[00477.htm|VDHFreezeVDM]]DOS session control service <br />[[00484.htm|VDHGetCodePageFont]]miscellaneous virtual DevHlp service <br />[[00493.htm|VDHGetDirtyPageInfo]]page-granular memory management service <br />[[00502.htm|VDHGetError]]miscellaneous virtual DevHlp service <br />[[00509.htm|VDHGetFlags]]miscellaneous virtual DevHlp service <br />[[00516.htm|VDHGetSelBase]]DPMI service <br />[[00524.htm|VDHGetVPMExcept]]DPMI service <br />[[00533.htm|VDHGetVPMIntVector]]DPMI service <br />[[00541.htm|VDHHaltSystem]]DOS session control service <br />[[00548.htm|VDHHandleFromPID]]miscellaneous virtual DevHlp service <br />[[00555.htm|VDHHandleFromSGID]]miscellaneous virtual DevHlp service <br />[[00562.htm|VDHInstallFaultHook]]page-granular memory management service <br />[[00573.htm|VDHInstallIntHook]]hook management service <br />[[00583.htm|VDHInstallIOHook]]hook management service <br />[[00594.htm|VDHInstallUserHook]]hook management service <br />[[00602.htm|VDHIsVDMFrozen]]DOS session control service <br />[[00609.htm|VDHKillVDM]]DOS session control service <br />[[00616.htm|VDHLockMem]]memory-locking memory management service <br />[[00627.htm|VDHMapPages]]page-granular memory management service <br />[[00636.htm|VDHOpen]]file or device I/O service <br />[[00650.htm|VDHOpenPDD]]inter-device communication service <br />[[00658.htm|VDHOpenVDD]]inter-device communication service <br />[[00665.htm|VDHOpenVIRQ]]Virtual interrupt service <br />[[00676.htm|VDHPhysicalDisk]]file or device I/O service <br />[[00687.htm|VDHPopInt]]V8086 stack manipulation service <br />[[00694.htm|VDHPopRegs]]V8086 stack manipulation service <br />[[00701.htm|VDHPopStack]]V8086 stack manipulation service <br />[[00709.htm|VDHPopup]]miscellaneous virtual DevHlp service <br />[[00721.htm|VDHPostEventSem]]semaphore service <br />[[00728.htm|VDHPrintClose]]parallel port and printer service <br />[[00735.htm|VDHPushFarCall]]V8086 stack manipulation service <br />[[00742.htm|VDHPushInt]]V8086 stack manipulation service <br />[[00749.htm|VDHPushRegs]]V8086 stack manipulation service <br />[[00756.htm|VDHPushStack]]V8086 stack manipulation service <br />[[00764.htm|VDHPutSysValue]]miscellaneous virtual DevHlp service <br />[[00772.htm|VDHQueryFreePages]]page-granular memory management service <br />[[00779.htm|VDHQueryHookData]]hook management service <br />[[00786.htm|VDHQueryLin]]miscellaneous virtual DevHlp service <br />[[00793.htm|VDHQueryKeyShift]]keyboard service <br />[[00800.htm|VDHQueryProperty]]DOS settings service <br />[[00807.htm|VDHQuerySel]]GDT selector service <br />[[00814.htm|VDHQuerySem]]semaphore service <br />[[00822.htm|VDHQuerySysValue]]miscellaneous virtual DevHlp service <br />[[00830.htm|VDHQueryVIRQ]]Virtual interrupt service <br />[[00838.htm|VDHRaiseException]]DPMI service <br />[[00847.htm|VDHRead]]file or device I/O service <br />[[00856.htm|VDHReadUBuf]]DPMI service <br />[[00867.htm|VDHReallocPages]]page-granular memory management service <br />[[00876.htm|VDHRegisterAPI]]Register API handler <br />[[00885.htm|VDHRegisterDMAChannel]]DMA service <br />[[00893.htm|VDHRegisterProperty]]DOS settings service <br />[[00908.htm|VDHRegisterVDD]]inter-device communication service <br />[[00917.htm|VDHReleaseCodePageFont]]miscellaneous virtual DevHlp service <br />[[00924.htm|VDHReleaseMutexSem]]semaphore service <br />[[00931.htm|VDHRemoveFaultHook]]page-granular memory management service <br />[[00941.htm|VDHRemoveIOHook]]hook management service <br />[[00951.htm|VDHReportPeek]]idle DOS application management service <br />[[00958.htm|VDHRequestMutexSem]]semaphore service <br />[[00966.htm|VDHRequestVDD]]inter-device communication service <br />[[00977.htm|VDHReservePages]]page-granular memory management service <br />[[00985.htm|VDHResetEventSem]]semaphore service <br />[[00992.htm|VDHSeek]]file or device I/O service <br />[[01001.htm|VDHSendVEOI]]Virtual interrupt service <br />[[01008.htm|VDHSetDosDevice]]miscellaneous virtual DevHlp service <br />[[01015.htm|VDHSetError]]miscellaneous virtual DevHlp service <br />[[01022.htm|VDHSetFlags]]miscellaneous virtual DevHlp service <br />[[01029.htm|VDHSetIOHookState]]hook management service <br />[[01040.htm|VDHSetPriority]]DOS session control service <br />[[01049.htm|VDHSetVIRR]]Virtual interrupt service <br />[[01057.htm|VDHSetVPMExcept]]DPMI service <br />[[01066.htm|VDHSetVPMIntVector]]DPMI service <br />[[01075.htm|VDHSwitchToVPM]]DPMI service <br />[[01082.htm|VDHSwitchToV86]]DPMI service <br />[[01089.htm|VDHThawVDM]]DOS session control service <br />[[01096.htm|VDHUnlockMem]]memory-locking memory management service <br />[[01103.htm|VDHUnreservePages]]page-granular memory management service <br />[[01111.htm|VDHWaitEventSem]]semaphore service <br />[[01119.htm|VDHWaitVIRRs]]Virtual interrupt service <br />[[01126.htm|VDHWakeIdle]]idle DOS application management service <br />[[01133.htm|VDHWakeVIRRs]]Virtual interrupt service <br />[[01140.htm|VDHWrite]]file or device I/O service <br />[[01149.htm|VDHWriteUBuf]]DPMI service <br />[[01160.htm|VDHYield]]DOS session control service
 
=== Some Notes on Virtual DevHlp Services ===
 
'''Passing Addresses of Buffers'''
 
The SSToDS macro must be used when passing the address of a frame ( automatic) variable in a function call because the 32-bit code assumes SS= DS. Pointers allocated from the stack must be DS-relative.
 
'''Function Definitions and Calling Conventions'''
 
All virtual DevHlp services are 32-bit NEAR functions. For a description of the calling conventions, refer to the function prototype definition VDHENTRY located in the MVDM.INC include file included with the ''Developer's Toolkit for OS/2''.
 
When using the virtual DevHlp services, the function being called is responsible for cleaning up the stack. This means that when you call a virtual DevHlp service, the function you call cleans up the stack; you do not have to pop the parameters off the stack after the call. This also means that when you register a hook (or callback) routine with a virtual DevHlp service, your hook routine is responsible for cleaning up the stack before it returns to the function that called it.
 
The virtual DevHlp services are called directly, as in CALL VDHFunction. This is in contrast to the physical device driver Device Helper services, which are called indirectly as in CALL [DevHlpFunction].
 
'''Syntax Examples'''
 
The syntax examples are shown in C language. For assembler language syntax examples, see [[01168.htm|Assembler Language Syntax]].
 
'''Defined Constants and Type Definitions'''
 
Defined constants, that is, ''equate''statements in an ''include''file, and type definitions are widely used in OS/2. These constant values are defined in the master header files, MVDM.INC or .h, or in one of the files that MVDM. INC or .h includes. The defined constants and type definitions that are seen in the syntax examples should be used to provide a degree of machine and version independence.
 
'''Invalid Parameters and System Halts'''
 
In many of the virtual DevHlp functions, invalid parameters or other error conditions often cause a system halt because virtual device drivers run at Ring 0 and have free access to everything in the system.
 
'''Remarks Section'''
 
Each function description has a '''Remarks'''section at the end, which consists of three parts:
 
*Context Issues: Indicates the specific contexts in which virtual DevHlps should be called.
 
*DOS Session Termination: Indicates what the virtual device driver must do upon termination of a DOS session, for example, release resources.
 
*Notes: These are miscellaneous function-specific notes about the function.
 
 
 
 
 
=== Virtual DevHlp Services by Category ===
 
Virtual DevHlp services can be divided into categories based on the type of service the virtual DevHlp provides. These categories are:
 
 
 
 
 
=== DMA Services ===
 
[[00159.htm|VDHAllocDMABuffer]]Allocate DMA buffer <br />[[00255.htm|VDHCallOutDMA]]Call virtual DMA device driver <br />[[00449.htm|VDHFreeDMABuffer]]Free DMA buffer <br />[[00885.htm|VDHRegisterDMAChannel]]Register DMA channel
 
 
 
 
 
=== DOS Session Control Services ===
 
[[00477.htm|VDHFreezeVDM]]Freeze DOS session <br />[[00541.htm|VDHHaltSystem]]Cause system halt <br />[[00602.htm|VDHIsVDMFrozen]]Determine if DOS session is frozen <br />[[00609.htm|VDHKillVDM]]Terminate DOS session <br />[[01040.htm|VDHSetPriority]]Adjust DOS session scheduler priority <br />[[01089.htm|VDHThawVDM]]Allow frozen DOS session to resume executing <br />[[01160.htm|VDHYield]]Yield the processor
 
 
 
 
 
=== DOS Settings Services ===
 
[[00348.htm|VDHDecodeProperty]]Decode property string <br />[[00800.htm|VDHQueryProperty]]Query virtual device driver property value <br />[[00893.htm|VDHRegisterProperty]]Register virtual device driver property
 
 
 
 
 
=== DPMI Services ===
 
[[00241.htm|VDHArmVPMBPHook]]Obtain address of DOS session protect-mode breakpoint <br />[[00248.htm|VDHBeginUseVPMStack]]Begin using DOS session protect-mode stack <br />[[00262.htm|VDHChangeVPMIF]]Change virtual Interrupt Flag (IF) <br />[[00269.htm|VDHCheckPagePerm]]Check Ring 3 page permissions <br />[[00279.htm|VDHCheckVPMIntVector]]Determine if DOS session protect-mode handler exists <br />[[00409.htm|VDHEndUseVPMStack]]End use of DOS session protect-mode stack <br />[[00516.htm|VDHGetSelBase]]Get flat base address <br />[[00524.htm|VDHGetVPMExcept]]Get DOS session protect-mode exception vector <br />[[00533.htm|VDHGetVPMIntVector]]Return DOS session protect-mode interrupt vector <br />[[00838.htm|VDHRaiseException]]Raise an exception to a DOS session <br />[[00856.htm|VDHReadUBuf]]Read from protect-mode address space <br />[[01057.htm|VDHSetVPMExcept]]Set DOS session protect-mode exception vector <br />[[01066.htm|VDHSetVPMIntVector]]Set DOS session protect-mode interrupt vector <br />[[01075.htm|VDHSwitchToVPM]]Switch DOS session to protect mode <br />[[01082.htm|VDHSwitchToV86]]Switch DOS session to V86 mode <br />[[01149.htm|VDHWriteUBuf]]Write to protect-mode address space
 
'''Note:'''&quot;VPM&quot;, as found in the function names above, stands for ''Virtual Protect Mode''.
 
 
 
 
 
=== File or Device I/O Services ===
 
[[00294.htm|VDHClose]]Close a file handle <br />[[00387.htm|VDHDevIOCtl]]Issue device-specific commands <br />[[00636.htm|VDHOpen]]Open a file or device <br />[[00676.htm|VDHPhysicalDisk]]Get information about partitionable disks <br />[[00847.htm|VDHRead]]Read bytes from file or device <br />[[00992.htm|VDHSeek]]Move read or write file pointer for a handle <br />[[01140.htm|VDHWrite]]Write bytes to file or device
 
 
 
 
 
=== GDT Selector Services ===
 
[[00332.htm|VDHCreateSel]]Create GDT selector to map a linear range <br />[[00365.htm|VDHDestroySel]]Destroy GDT selector <br />[[00807.htm|VDHQuerySel]]Get selector for data or stack address
 
 
 
 
 
=== Hook Management Services ===
 
[[00175.htm|VDHAllocHook]]Allocate hooks needed for interrupt simulation <br />[[00201.htm|VDHArmBPHook]]Obtain address of V86 breakpoint <br />[[00208.htm|VDHArmContextHook]]Set local or global context hook <br />[[00216.htm|VDHArmReturnHook]]Set handler to receive control <br />[[00224.htm|VDHArmSTIHook]]Set handler to receive control <br />[[00456.htm|VDHFreeHook]]Disarm and free hook <br />[[00573.htm|VDHInstallIntHook]]Set handler for V86 interrupt <br />[[00583.htm|VDHInstallIOHook]]Install I/O port hooks <br />[[00594.htm|VDHInstallUserHook]]Install handler for DOS session event <br />[[00779.htm|VDHQueryHookData]]Returns pointer to hook reference data <br />[[00941.htm|VDHRemoveIOHook]]Remove hooks for PIC I/O ports <br />[[01029.htm|VDHSetIOHookState]]Enable/disable I/O port trapping
 
 
 
 
 
=== Idle DOS Application Management Services ===
 
[[00951.htm|VDHReportPeek]]Report DOS session polling activity <br />[[01126.htm|VDHWakeIdle]]Wake up DOS session
 
'''Note:'''The services above indicate when a DOS application appears to be idle, and when activity exists that could make the DOS application BUSY.
 
 
 
 
 
=== Inter-Device-Communication Services ===
 
[[00301.htm|VDHCloseVDD]]Close virtual device driver <br />[[00650.htm|VDHOpenPDD]]Open physical device driver <br />[[00658.htm|VDHOpenVDD]]Open virtual device driver <br />[[00908.htm|VDHRegisterVDD]]Register virtual device driver entry points <br />[[00966.htm|VDHRequestVDD]]Issue request for virtual device driver operation
 
 
 
 
 
=== Keyboard Services ===
 
[[00793.htm|VDHQueryKeyShift]]Query keyboard shift state
 
 
 
 
 
=== Memory Management Services ===
 
There are three sub-categories of the memory management virtual DevHlp services. The first two are used for the granularity of the memory allocation unit; the third category is used for memory-locking services.
 
 
 
 
 
=== Byte-Granular Memory Management Services ===
 
[[00152.htm|VDHAllocBlock]]Allocate block from memory block pool <br />[[00168.htm|VDHAllocDOSMem]]Allocate block of memory from DOS area <br />[[00184.htm|VDHAllocMem]]Allocate small amount of memory <br />[[00315.htm|VDHCopyMem]]Copy from one linear memory address to another <br />[[00324.htm|VDHCreateBlockPool]]Create memory block pool <br />[[00358.htm|VDHDestroyBlockPool]]Destroy memory block pool <br />[[00424.htm|VDHExchangeMem]]Exchange contents of two linear memory regions <br />[[00441.htm|VDHFreeBlock]]Free block of memory <br />[[00463.htm|VDHFreeMem]]Free memory
 
 
 
 
 
=== Page-Granular Memory Management Services ===
 
[[00192.htm|VDHAllocPages]]Allocate page-aligned memory object <br />[[00433.htm|VDHFindFreePages]]Find largest available linear memory <br />[[00470.htm|VDHFreePages]]Free memory object <br />[[00493.htm|VDHGetDirtyPageInfo]]Return status of dirty bits <br />[[00562.htm|VDHInstallFaultHook]]Install page fault handler <br />[[00627.htm|VDHMapPages]]Map specified linear address <br />[[00772.htm|VDHQueryFreePages]]Return amount of free virtual memory <br />[[00867.htm|VDHReallocPages]]Reallocate memory object <br />[[00931.htm|VDHRemoveFaultHook]]Remove page fault handler <br />[[00977.htm|VDHReservePages]]Reserve range of linear addresses <br />[[01103.htm|VDHUnreservePages]]Unreserve range of linear addresses
 
 
 
 
 
=== Memory-Locking Memory Management Services ===
 
[[00616.htm|VDHLockMem]]Verify access or lock memory <br />[[01096.htm|VDHUnlockMem]]Release memory lock
 
'''Note:'''The services above allow virtual device drivers to allocate, free, reallocate, and lock memory for global, per-DOS session, page-granular, or byte-granular objects.
 
Four types of mappings are supported:
 
*Mapping to a physical address <br />*Mapping to another linear address <br />*Mapping to black holes (don't care) pages <br />*Mapping to invalid (unmapped) pages
 
Virtual device drivers can also request smaller memory allocations from the kernel heap, which is global and fixed. Small, fixed size block services are available to speed up frequent allocations and freeing of memory. For a particular block size, a pool of blocks is maintained and the requirements are met by taking off a block from the block pool.
 
 
 
 
 
=== Miscellaneous Virtual DevHlp Services ===
 
[[00379.htm|VDHDevBeep]]Device beep virtual DevHlp service <br />[[00416.htm|VDHEnumerateVDMs]]Run worker function for each DOS session <br />[[00484.htm|VDHGetCodePageFont]]Return information of DOS session code page font <br />[[00502.htm|VDHGetError]]Get error code from last virtual DevHlp service <br />[[00509.htm|VDHGetFlags]]Get DOS Session's EFLAGS Register <br />[[00548.htm|VDHHandleFromPID]]Get handle for given Process ID <br />[[00555.htm|VDHHandleFromSGID]]Get DOS session handle from Screen Group ID <br />[[00709.htm|VDHPopup]]Display message <br />[[00764.htm|VDHPutSysValue]]Set system value <br />[[00786.htm|VDHQueryLin]]Get linear address for Far16 address <br />[[00822.htm|VDHQuerySysValue]]Query system value <br />[[00876.htm|VDHRegisterAPI]]Register API handler <br />[[00917.htm|VDHReleaseCodePageFont]]Release code page font <br />[[01008.htm|VDHSetDosDevice]]Register/install DOS device driver <br />[[01015.htm|VDHSetError]]Set error code <br />[[01022.htm|VDHSetFlags]]Set DOS session flags register
 
 
 
 
 
=== Parallel Port and Printer Services ===
 
[[00728.htm|VDHPrintClose]]Flush and close open printers for DOS session
 
 
 
 
 
=== Semaphore Services ===
 
[[00340.htm|VDHCreateSem]]Create event or mutex semaphore <br />[[00372.htm|VDHDestroySem]]Destroy semaphore <br />[[00721.htm|VDHPostEventSem]]Post event semaphore <br />[[00814.htm|VDHQuerySem]]Query semaphore state <br />[[00924.htm|VDHReleaseMutexSem]]Release mutex semaphore <br />[[00958.htm|VDHRequestMutexSem]]Request mutex semaphore <br />[[00985.htm|VDHResetEventSem]]Reset event semaphore <br />[[01111.htm|VDHWaitEventSem]]Wait on event semaphore
 
'''Note:'''The services above are used for synchronizing with an OS/2 process. Virtual device drivers must be careful not to block (''VDHRequestMutexSem/ VDHWaitEventSem'') in the context of a DOS session task. Otherwise, that task will receive no more simulated hardware interrupts until it becomes unblocked.
 
 
 
 
 
=== Timer Services ===
 
[[00232.htm|VDHArmTimerHook]]Set timer service/handler <br />[[00402.htm|VDHDisarmTimerHook]]Cancel timer service
 
 
 
 
 
=== Virtual Interrupt Services ===
 
[[00286.htm|VDHClearVIRR]]Clear virtual IRR <br />[[00308.htm|VDHCloseVIRQ]]Deregister IRQ handler <br />[[00665.htm|VDHOpenVIRQ]]Register IRQ handler <br />[[00830.htm|VDHQueryVIRQ]]Query IRQ status on a DOS session <br />[[01001.htm|VDHSendVEOI]]Send virtual EOI to VPIC <br />[[01049.htm|VDHSetVIRR]]Set virtual interrupt request register (IRR) <br />[[01119.htm|VDHWaitVIRRs]]Wait until interrupt is simulated <br />[[01133.htm|VDHWakeVIRRs]]Wake up DOS session
 
 
 
 
 
=== V8086 Stack Manipulation Services ===
 
[[00687.htm|VDHPopInt]]Remove IRET frame from client DOS session stack <br />[[00694.htm|VDHPopRegs]]Pop client DOS session registers from client stack <br />[[00701.htm|VDHPopStack]]Pop data off client stack <br />[[00735.htm|VDHPushFarCall]]Simulate Far Call to V86 code <br />[[00742.htm|VDHPushInt]]Transfer control to V86 interrupt handler <br />[[00749.htm|VDHPushRegs]]Push client DOS session registers onto client stack <br />[[00756.htm|VDHPushStack]]Push data onto client stack
 
 
 
 
 
=== VDHAllocBlock ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function allocates a block from the specified memory block pool. This block is allocated from fixed or swappable memory, depending on the value of the ''OptionFlag''flag when the block is created with ''VDHCreateBlockPool''.
 
<pre class="western">#include mvdm.h
 
HBLOCK    SourceBlockPool;  /*  Handle to a memory block pool */
PVOID    rc;
 
rc = VDHAllocBlock(SourceBlockPool);</pre>
 
 
 
 
=== VDHAllocBlock - Format ===
 
This function allocates a block from the specified memory block pool. This block is allocated from fixed or swappable memory, depending on the value of the ''OptionFlag''flag when the block is created with ''VDHCreateBlockPool''.
 
<pre class="western">#include mvdm.h
 
HBLOCK    SourceBlockPool;  /*  Handle to a memory block pool */
PVOID    rc;
 
rc = VDHAllocBlock(SourceBlockPool);</pre>
 
 
 
 
=== VDHAllocBlock Parameter - SourceBlockPool ===
 
'''SourceBlockPool'''(HBLOCK) Handle to the pool of memory blocks from which to allocate a memory block.
 
 
 
 
 
=== VDHAllocBlock Return Value - rc ===
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the address of the allocated memory block.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. Note that passing an invalid memory block handle causes a system halt to occur.
 
 
 
 
 
=== VDHAllocBlock - Parameters ===
 
'''SourceBlockPool'''(HBLOCK) Handle to the pool of memory blocks from which to allocate a memory block.
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the address of the allocated memory block.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. Note that passing an invalid memory block handle causes a system halt to occur.
 
 
 
 
 
=== VDHAllocBlock - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: Any blocks allocated by a virtual device driver for use by the terminating DOS session are freed by using ''VDHFreeBlock''. Any block pools created for the DOS session should also be freed.
 
 
 
 
 
=== VDHAllocBlock - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHAllocDMABuffer ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function allocates a DMA buffer.
 
<pre class="western">#include mvdm.h
 
ULONG    RequestSize;  /*  Request size */
BOOL      Align64kFlag;  /*  Alignment flag */
PULONG    PhysAddrPtr;  /*  Location to store the physical address returned */
PVOID    rc;
 
rc = VDHAllocDMABuffer(RequestSize, Align64kFlag,
      PhysAddrPtr);</pre>
 
 
 
 
=== VDHAllocDMABuffer - Format ===
 
This function allocates a DMA buffer.
 
<pre class="western">#include mvdm.h
 
ULONG    RequestSize;  /*  Request size */
BOOL      Align64kFlag;  /*  Alignment flag */
PULONG    PhysAddrPtr;  /*  Location to store the physical address returned */
PVOID    rc;
 
rc = VDHAllocDMABuffer(RequestSize, Align64kFlag,
      PhysAddrPtr);</pre>
 
 
 
 
=== VDHAllocDMABuffer Parameter - RequestSize ===
 
'''RequestSize'''(ULONG) Request Size.
 
If the ''Align64kFlag''=1, ''RequestSize''is always less than or equal to 64KB. If the ''Align64kFlag''=0, ''RequestSize''is always less than or equal to 128KB.
 
 
 
 
 
=== VDHAllocDMABuffer Parameter - Align64kFlag ===
 
'''Align64kFlag'''(BOOL) Alignment flag.
 
If ''Align64kFlag''=1, the buffer is at a 64KB alignment in physical memory. If ''Align64kFlag''=0, the buffer is at a 128KB alignment in physical memory.
 
 
 
 
 
=== VDHAllocDMABuffer Parameter - PhysAddrPtr ===
 
'''PhysAddrPtr'''(PULONG) Location where ''VDHAllocDMABuffer''returns the physical address of the allocation.
 
 
 
 
 
=== VDHAllocDMABuffer Return Value - rc ===
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the linear address of allocation (system memory).
 
Failure If the function fails, it returns -1. ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHAllocDMABuffer - Parameters ===
 
'''RequestSize'''(ULONG) Request Size.
 
If the ''Align64kFlag''=1, ''RequestSize''is always less than or equal to 64KB. If the ''Align64kFlag''=0, ''RequestSize''is always less than or equal to 128KB.
 
'''Align64kFlag'''(BOOL) Alignment flag.
 
If ''Align64kFlag''=1, the buffer is at a 64KB alignment in physical memory. If ''Align64kFlag''=0, the buffer is at a 128KB alignment in physical memory.
 
'''PhysAddrPtr'''(PULONG) Location where ''VDHAllocDMABuffer''returns the physical address of the allocation.
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the linear address of allocation (system memory).
 
Failure If the function fails, it returns -1. ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHAllocDMABuffer - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: The virtual device driver frees the buffer by using ''VDHFreeDMABuffer''at DOS session termination.
 
Notes: Physical memory is allocated resident and contiguous, and is always in the first 16MB. The Linear Memory range comes from the system arena. The contents of the returned buffer are not important; that is, the buffer is not zero-filled.
 
 
 
 
 
=== VDHAllocDMABuffer - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHAllocDOSMem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function allocates a block of memory from the DOS memory area. Allocations start at 0 bytes and go to 256KB.
 
<pre class="western">#include mvdm.h
 
ULONG    BlockSize;  /*  Size of the desired memory block (in bytes) */
PVOID    rc;
 
rc = VDHAllocDOSMem(BlockSize);</pre>
 
 
 
 
=== VDHAllocDOSMem - Format ===
 
This function allocates a block of memory from the DOS memory area. Allocations start at 0 bytes and go to 256KB.
 
<pre class="western">#include mvdm.h
 
ULONG    BlockSize;  /*  Size of the desired memory block (in bytes) */
PVOID    rc;
 
rc = VDHAllocDOSMem(BlockSize);</pre>
 
 
 
 
=== VDHAllocDOSMem Parameter - BlockSize ===
 
'''BlockSize'''(ULONG) Size of the desired memory block; the number of bytes to allocate.
 
 
 
 
 
=== VDHAllocDOSMem Return Value - rc ===
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the address of the allocated memory block.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. If ''BlockSize''= 0, or if the function is called in an invalid context (see &quot;Context Issues&quot; below), a system halt occurs.
 
 
 
 
 
=== VDHAllocDOSMem - Parameters ===
 
'''BlockSize'''(ULONG) Size of the desired memory block; the number of bytes to allocate.
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the address of the allocated memory block.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. If ''BlockSize''= 0, or if the function is called in an invalid context (see &quot;Context Issues&quot; below), a system halt occurs.
 
 
 
 
 
=== VDHAllocDOSMem - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context (DOS session creation).
 
DOS Session Terminations: There are no DOS session termination implications for this function. The DOS Session Manager frees this memory.
 
Notes: There is no way to free memory taken from the DOS heap. If there is no free memory in the DOS memory area, the allocation fails. Allocations always start on paragraph (16-byte) boundaries.
 
 
 
 
 
=== VDHAllocDOSMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHAllocHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used to allocate a hook handle for the arm hook services: Context, STI, Return, Timer, and BP (breakpoint).
 
<pre class="western">#include mvdm.h
 
ULONG    HookType;    /*  Hook type */
PFNARM    ArmHookFcn;  /*  Arm hook function */
ULONG    RefDataSize;  /*  Size of the reference data */
HHOOK    rc;
 
rc = VDHAllocHook(HookType, ArmHookFcn, RefDataSize);</pre>
 
 
 
 
=== VDHAllocHook - Format ===
 
This function is used to allocate a hook handle for the arm hook services: Context, STI, Return, Timer, and BP (breakpoint).
 
<pre class="western">#include mvdm.h
 
ULONG    HookType;    /*  Hook type */
PFNARM    ArmHookFcn;  /*  Arm hook function */
ULONG    RefDataSize;  /*  Size of the reference data */
HHOOK    rc;
 
rc = VDHAllocHook(HookType, ArmHookFcn, RefDataSize);</pre>
 
 
 
 
=== VDHAllocHook Parameter - HookType ===
 
'''HookType'''(ULONG) Hook type.
 
Possible values are:
 
VDH_CONTEXT_HOOK VDHArmContextHook <br />VDH_STI_HOOK VDHArmSTIHook <br />VDH_RETURN_HOOK VDHArmReturnHook <br />VDH_TIMER_HOOK VDHArmTimerHook <br />VDH_BP_HOOK VDHArmBPHook
 
 
 
 
 
=== VDHAllocHook Parameter - ArmHookFcn ===
 
'''ArmHookFcn'''(PFNARM) Arm hook function.
 
 
 
 
 
=== VDHAllocHook Parameter - RefDataSize ===
 
'''RefDataSize'''(ULONG) Size of the reference data.
 
 
 
 
 
=== VDHAllocHook Return Value - rc ===
 
'''rc'''(HHOOK) - returns
 
Success If the function is successful, it returns a hook handle, which is used in the Arm services.
 
Failure If there is an error, the function returns NULL. ''VDHGetError''should be called to determine the nature of the problem. If ''HookType''or ''ArmHookFcn''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHAllocHook - Parameters ===
 
'''HookType'''(ULONG) Hook type.
 
Possible values are:
 
VDH_CONTEXT_HOOK VDHArmContextHook <br />VDH_STI_HOOK VDHArmSTIHook <br />VDH_RETURN_HOOK VDHArmReturnHook <br />VDH_TIMER_HOOK VDHArmTimerHook <br />VDH_BP_HOOK VDHArmBPHook
 
'''ArmHookFcn'''(PFNARM) Arm hook function.
 
'''RefDataSize'''(ULONG) Size of the reference data.
 
'''rc'''(HHOOK) - returns
 
Success If the function is successful, it returns a hook handle, which is used in the Arm services.
 
Failure If there is an error, the function returns NULL. ''VDHGetError''should be called to determine the nature of the problem. If ''HookType''or ''ArmHookFcn''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHAllocHook - Purpose ===
 
Context Issues: This function can be called in the initialization or DOS session-task context. However, VDH_RETURN_HOOK and VDH_BP_HOOK require the DOS session-task context.
 
DOS Session Terminations: During initialization time, hooks are allocated globally; that is, they are not associated with a DOS session process. These hooks are not automatically freed when a DOS session terminates. During DOS session creation time or thereafter, allocated hooks are associated with the current DOS session, and are freed when that DOS session terminates.
 
Notes: Use ''VDHQueryHookData''to get a pointer to any reference data allocated.
 
 
 
 
 
=== VDHAllocHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHAllocMem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function allocates a small amount of memory on a LONG/DWORD boundary. The memory is allocated from the system area, so the address is valid in all process contexts.
 
<pre class="western">#include mvdm.h
 
ULONG    NumBytes;
ULONG    OptionFlag;  /*  Number of bytes to allocate */
PVOID    rc;
 
rc = VDHAllocMem(NumBytes, OptionFlag);</pre>
 
 
 
 
=== VDHAllocMem - Format ===
 
This function allocates a small amount of memory on a LONG/DWORD boundary. The memory is allocated from the system area, so the address is valid in all process contexts.
 
<pre class="western">#include mvdm.h
 
ULONG    NumBytes;
ULONG    OptionFlag;  /*  Number of bytes to allocate */
PVOID    rc;
 
rc = VDHAllocMem(NumBytes, OptionFlag);</pre>
 
 
 
 
=== VDHAllocMem Parameter - NumBytes ===
 
'''NumBytes'''(ULONG) Number of bytes to allocate.
 
 
 
 
 
=== VDHAllocMem Parameter - OptionFlag ===
 
'''OptionFlag'''(ULONG) Bit flag describing the allocation options.
 
Possible value:
 
VDHAM_SWAPPABLE Allocate memory from the swappable heap. Otherwise, memory is allocated from the fixed heap and can be accessed at hardware interrupt time.
 
 
 
 
 
=== VDHAllocMem Return Value - rc ===
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the address of the allocated space.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. If either ''NumBytes''or ''OptionFlag''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHAllocMem - Parameters ===
 
'''NumBytes'''(ULONG) Number of bytes to allocate.
 
'''OptionFlag'''(ULONG) Bit flag describing the allocation options.
 
Possible value:
 
VDHAM_SWAPPABLE Allocate memory from the swappable heap. Otherwise, memory is allocated from the fixed heap and can be accessed at hardware interrupt time.
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the address of the allocated space.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. If either ''NumBytes''or ''OptionFlag''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHAllocMem - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: All memory allocated by a virtual device driver for use by the terminating DOS session is freed by using ''VDHFreeMem''.
 
Notes: Allocations larger than one page are performed by using ''VDHAllocPages''. To access the allocated memory at hardware interrupt time, be sure to allocate memory from the fixed heap.
 
 
 
 
 
=== VDHAllocMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHAllocPages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function allocates a page-aligned, page-granular memory object.
 
<pre class="western">#include mvdm.h
 
PVOID    StartingAddress;  /*  A specific linear address */
ULONG    NumPages;        /*  The number of pages to allocate */
ULONG    OptionFlag;      /*  Allocation options bit-flag */
PVOID    rc;
 
rc = VDHAllocPages(StartingAddress, NumPages,
      OptionFlag);</pre>
 
 
 
 
=== VDHAllocPages - Format ===
 
This function allocates a page-aligned, page-granular memory object.
 
<pre class="western">#include mvdm.h
 
PVOID    StartingAddress;  /*  A specific linear address */
ULONG    NumPages;        /*  The number of pages to allocate */
ULONG    OptionFlag;      /*  Allocation options bit-flag */
PVOID    rc;
 
rc = VDHAllocPages(StartingAddress, NumPages,
      OptionFlag);</pre>
 
 
 
 
=== VDHAllocPages Parameter - StartingAddress ===
 
'''StartingAddress'''(PVOID) A specific address used with the available options (see ''Option Flag'').
 
 
 
 
 
=== VDHAllocPages Parameter - NumPages ===
 
'''NumPages'''(ULONG) Number of pages of linear memory to allocate.
 
 
 
 
 
=== VDHAllocPages Parameter - OptionFlag ===
 
'''OptionFlag'''(ULONG) Bit flag indicating choices in allocation options.
 
This flag can take one or more of the following values:
 
VDHAP_SPECIFIC ''VDHAllocPages''attempts to allocate pages starting at the linear address, ''StartingAddress''. Otherwise, an arbitrary linear address is selected.
 
VDHAP_SYSTEM The linear address is allocated from the system (global) area, essentially allocating global memory. Otherwise, it is allocated from the private area of this process.
 
VDHAP_FIXED The allocated memory is fixed. Otherwise, the memory is swappable. This flag cannot be used if VDHAP_PHYSICAL is specified.
 
VDHAP_PHYSICAL The allocated linear address range maps the physical address range, starting at ''StartingAddress''. Otherwise, an arbitrary physical page is assigned. Note that this flag cannot be used if VDHAP_FIXED is specified .
 
 
 
 
 
=== VDHAllocPages Return Value - rc ===
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the address of the allocated memory.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. If the ''OptionFlag''flag is invalid, a system halt occurs.
 
 
 
 
 
=== VDHAllocPages - Parameters ===
 
'''StartingAddress'''(PVOID) A specific address used with the available options (see ''Option Flag'').
 
'''NumPages'''(ULONG) Number of pages of linear memory to allocate.
 
'''OptionFlag'''(ULONG) Bit flag indicating choices in allocation options.
 
This flag can take one or more of the following values:
 
VDHAP_SPECIFIC ''VDHAllocPages''attempts to allocate pages starting at the linear address, ''StartingAddress''. Otherwise, an arbitrary linear address is selected.
 
VDHAP_SYSTEM The linear address is allocated from the system (global) area, essentially allocating global memory. Otherwise, it is allocated from the private area of this process.
 
VDHAP_FIXED The allocated memory is fixed. Otherwise, the memory is swappable. This flag cannot be used if VDHAP_PHYSICAL is specified.
 
VDHAP_PHYSICAL The allocated linear address range maps the physical address range, starting at ''StartingAddress''. Otherwise, an arbitrary physical page is assigned. Note that this flag cannot be used if VDHAP_FIXED is specified .
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the address of the allocated memory.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. If the ''OptionFlag''flag is invalid, a system halt occurs.
 
 
 
 
 
=== VDHAllocPages - Purpose ===
 
Context Issues: This function can be called in the initialization or task context. If called in the initialization context, VDHAP_SYSTEM must be specified. If called in the OS/2 task context, VDHAP_SYSTEM must also be specified.
 
DOS Session Terminations: Any allocations that are not in the terminating DOS sessions private area must be released by using ''VDHFreePages''.
 
Notes: When an allocation made with ''VDHAllocPages''is shrunk by ''VDHReallocPages'', the linear range between the end of the allocation and the original end of the allocation remains available for object growth without movement. Regardless of ''VDHReallocPages''activity, all pages in the allocation retain the same properties (that is fixed, system, and physical) .
 
 
 
 
 
=== VDHAllocPages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHArmBPHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function obtains the address of the V86 breakpoint allocated by a previous call to ''VDHAllocHook''with the VDH_BP_HOOK flag.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle */
VPVOID    rc;
 
rc = VDHArmBPHook(HookHandle);</pre>
 
 
 
 
=== VDHArmBPHook - Format ===
 
This function obtains the address of the V86 breakpoint allocated by a previous call to ''VDHAllocHook''with the VDH_BP_HOOK flag.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle */
VPVOID    rc;
 
rc = VDHArmBPHook(HookHandle);</pre>
 
 
 
 
=== VDHArmBPHook Parameter - HookHandle ===
 
'''HookHandle'''(HHOOK) Hook handle allocated with ''VDHAllocHook''.
 
Hook routine interface:
 
<pre class="western"> VOID HOOKENTRY fnarm(pRefData, pcrf)
      ENTRY    pRefData - Pointer to hook-specific reference data
                pcrf    - Pointer to client register frame
      EXIT      None
      CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHArmBPHook Return Value - rc ===
 
'''rc'''(VPVOID) - returns
 
Success If the function is successful, it returns a V86 breakpoint address.
 
Failure If ''HookHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHArmBPHook - Parameters ===
 
'''HookHandle'''(HHOOK) Hook handle allocated with ''VDHAllocHook''.
 
Hook routine interface:
 
<pre class="western"> VOID HOOKENTRY fnarm(pRefData, pcrf)
      ENTRY    pRefData - Pointer to hook-specific reference data
                pcrf    - Pointer to client register frame
      EXIT      None
      CONTEXT  DOS session-task</pre>
 
 
'''rc'''(VPVOID) - returns
 
Success If the function is successful, it returns a V86 breakpoint address.
 
Failure If ''HookHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHArmBPHook - Purpose ===
 
Context Issues: This function can be called only in the task context, and needs to be called only at DOS session creation time.
 
DOS Session Terminations: There are no DOS session termination implications for this function. BP (breakpoint) hooks are automatically removed during DOS session termination.
 
Notes: This VDH service provides a raw breakpoint service. Upon entry to the arm hook function, the client's CS:IP is randomly set. Therefore, it is crucial that this function set the CS:IP to a valid address. Typically, the CS:IP is retrieved from the client's stack through use of ''VDHPopStack''. This is a low-level service. Appropriate care should be exercised to ensure that the client's CS:IP and stack remain valid.
 
Unlike other hooks, breakpoint hooks are armed until explicitly disarmed by a call to ''VDHFreeHook''. When the V86 breakpoint address is called from V86 mode, the hook function is called. Any changes made to the client register frame cause the corresponding registers to take on these values upon return to V86 mode. The ''p''parameter in the hook routine points to the ''cbRefData''bytes of data allocated by ''VDHAllocHook''.
 
 
 
 
 
=== VDHArmBPHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHArmContextHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used to get to a task-time context from interrupt time when an interrupt is simulated. This service adds a handler to the list of routines called the next time the task context is entered (global context), or the next time a specific DOS session-task context is reached (local context). This is done only once; the handler is removed from the list after it is executed.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle allocated with VDHAllocHook */
HVDM    VDMHandle;  /*  DOS session handle */
 
VDHArmContextHook(HookHandle, VDMHandle);</pre>
 
 
 
 
=== VDHArmContextHook - Format ===
 
This function is used to get to a task-time context from interrupt time when an interrupt is simulated. This service adds a handler to the list of routines called the next time the task context is entered (global context), or the next time a specific DOS session-task context is reached (local context). This is done only once; the handler is removed from the list after it is executed.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle allocated with VDHAllocHook */
HVDM    VDMHandle;  /*  DOS session handle */
 
VDHArmContextHook(HookHandle, VDMHandle);</pre>
 
 
 
 
=== VDHArmContextHook Parameter - HookHandle ===
 
'''HookHandle'''(HHOOK) Hook handle allocated with ''VDHAllocHook''.
 
 
 
 
 
=== VDHArmContextHook Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) DOS session handle. A value of -1 indicates a global context.
 
Hook routine interface:
 
<pre class="western"> VOID HOOKENTRY fnarm(pRefData, pcrf)
      ENTRY    pRefData - Pointer to reference data
              pcrf    - Pointer to client register frame
      EXIT    None
      USES    EAX, ECX, EDX, FS, GS, Flags
      CONTEXT  Task (global) or DOS session-task (local)
      NOTE    pcrf is valid only for local context hook handlers</pre>
 
 
 
 
 
 
=== VDHArmContextHook - Return Value ===
 
Success If the function was successful, it returns nothing.
 
Failure If ''HookHandle''or ''VDMHandle''is invalid, or if the hook is already armed, a system halt occurs.
 
 
 
 
 
=== VDHArmContextHook - Parameters ===
 
'''HookHandle'''(HHOOK) Hook handle allocated with ''VDHAllocHook''.
 
'''VDMHandle'''(HVDM) DOS session handle. A value of -1 indicates a global context.
 
Hook routine interface:
 
<pre class="western"> VOID HOOKENTRY fnarm(pRefData, pcrf)
      ENTRY    pRefData - Pointer to reference data
              pcrf    - Pointer to client register frame
      EXIT    None
      USES    EAX, ECX, EDX, FS, GS, Flags
      CONTEXT  Task (global) or DOS session-task (local)
      NOTE    pcrf is valid only for local context hook handlers</pre>
 
 
Success If the function was successful, it returns nothing.
 
Failure If ''HookHandle''or ''VDMHandle''is invalid, or if the hook is already armed, a system halt occurs.
 
 
 
 
 
=== VDHArmContextHook - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: Any context hooks allocated in the context of the terminating DOS session are deallocated by the DOS Session Manager.
 
Notes: After calling this routine, the caller is guaranteed that the context hook will be executed before any user-space code (global context) or any V86 code in the specified DOS session (local context).
 
 
 
 
 
=== VDHArmContextHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHArmReturnHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function sets a service to receive control when an Interrupt Return ( IRET) or Far Return (RETF) instruction is executed in V86 mode or when ''VDHPopInt''is executed.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle */
ULONG    RetHookType;  /*  Return hook type */
BOOL    rc;
 
rc = VDHArmReturnHook(HookHandle, RetHookType);</pre>
 
 
 
 
=== VDHArmReturnHook - Format ===
 
This function sets a service to receive control when an Interrupt Return ( IRET) or Far Return (RETF) instruction is executed in V86 mode or when ''VDHPopInt''is executed.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle */
ULONG    RetHookType;  /*  Return hook type */
BOOL    rc;
 
rc = VDHArmReturnHook(HookHandle, RetHookType);</pre>
 
 
 
 
=== VDHArmReturnHook Parameter - HookHandle ===
 
'''HookHandle'''(HHOOK) Hook handles the routine to get control on an IRET/RETF. Allocated with ''VDHAllocHook''.
 
 
 
 
 
=== VDHArmReturnHook Parameter - RetHookType ===
 
'''RetHookType'''(ULONG) Return hook type.
 
Possible values are:
 
VDHARH_NORMAL_IRET <br />VDHARH_NORMAL_RET <br />VDHARH_RECURSIVE_IRET <br />VDHARH_RECURSIVE_RET <br />VDHARH_CSEIP_HOOK <br />VDHARH_RECURSIVE_CSEIP_HOOK
 
Hook routine interface:
 
<pre class="western">VOID HOOKENTRY fnarm(pRefData, pcrf)
    ENTRY    pRefData - Pointer to reference data
              pcrf    - Pointer to client register frame
    EXIT    None
    USES    EAX, ECX, EDX, FS, GS, Flags
    CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHArmReturnHook Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function was successful it returns a nonzero value.
 
Failure If VDHARH_NORMAL_x is already armed, the function returns 0. If ''HookHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHArmReturnHook - Parameters ===
 
'''HookHandle'''(HHOOK) Hook handles the routine to get control on an IRET/RETF. Allocated with ''VDHAllocHook''.
 
'''RetHookType'''(ULONG) Return hook type.
 
Possible values are:
 
VDHARH_NORMAL_IRET <br />VDHARH_NORMAL_RET <br />VDHARH_RECURSIVE_IRET <br />VDHARH_RECURSIVE_RET <br />VDHARH_CSEIP_HOOK <br />VDHARH_RECURSIVE_CSEIP_HOOK
 
Hook routine interface:
 
<pre class="western">VOID HOOKENTRY fnarm(pRefData, pcrf)
    ENTRY    pRefData - Pointer to reference data
              pcrf    - Pointer to client register frame
    EXIT    None
    USES    EAX, ECX, EDX, FS, GS, Flags
    CONTEXT  DOS session-task</pre>
 
 
'''rc'''(BOOL) - returns
 
Success If the function was successful it returns a nonzero value.
 
Failure If VDHARH_NORMAL_x is already armed, the function returns 0. If ''HookHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHArmReturnHook - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: Any return hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager.
 
Notes: The VDHARH_NORMAL_RET and VDHARH_RECURSIVE_RET return hook types can be made only after ''VDHPushFarCall''has been called, but before returning to V86 mode. The return hook types, VDHARH_NORMAL_IRET and VDHARH_RECURSIVE_ IRET, can be made only in the following contexts:
 
*Within a software interrupt handler set by ''VDHInstallIntHook''<br />*After ''VDHPushInt''has been called, but before returning to V86 mode
 
The VDHARH_RECURSIVE_x return types push two extra WORDs on the client's stack before the IRET or RET frame. VDHARH_CSEIP_HOOK and VDHARH_RECURSIVE_ CSEIP_HOOK are meant to be used before a ''VDHPushInt''or ''VDHPushFarCall'', as it is more efficient to do this type of return hook first. Only the normal and recursive CS:EIP hooks will work in DOS session protected mode.
 
 
 
 
 
=== VDHArmReturnHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHArmSTIHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function sets a handler to receive control when the current DOS session enables simulated interrupts. This handler is called only once. If interrupts are already enabled in the DOS session, the handler is called immediately.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle allocated with VDHAllocHook */
HVDM    VDMHandle;  /*  DOS session handle */
 
VDHArmSTIHook(HookHandle, VDMHandle);</pre>
 
 
 
 
=== VDHArmSTIHook - Format ===
 
This function sets a handler to receive control when the current DOS session enables simulated interrupts. This handler is called only once. If interrupts are already enabled in the DOS session, the handler is called immediately.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle allocated with VDHAllocHook */
HVDM    VDMHandle;  /*  DOS session handle */
 
VDHArmSTIHook(HookHandle, VDMHandle);</pre>
 
 
 
 
=== VDHArmSTIHook Parameter - HookHandle ===
 
'''HookHandle'''(HHOOK) Hook handle allocated with ''VDHAllocHook''.
 
 
 
 
 
=== VDHArmSTIHook Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) DOS session handle.
 
Hook routine interface:
 
<pre class="western"> VOID HOOKENTRY fnarm(pRefData, pcrf)
      ENTRY    pRefData - Pointer to reference data
              pcrf    - Pointer to client register frame
      EXIT    None
      USES    EAX, ECX, EDX, FS, GS, Flags
      CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHArmSTIHook - Return Value ===
 
Success If the function was successful, it returns nothing.
 
Failure If either ''HookHandle''or ''VDMHandle''is invalid, or if the hook is already armed, a system halt occurs.
 
 
 
 
 
=== VDHArmSTIHook - Parameters ===
 
'''HookHandle'''(HHOOK) Hook handle allocated with ''VDHAllocHook''.
 
'''VDMHandle'''(HVDM) DOS session handle.
 
Hook routine interface:
 
<pre class="western"> VOID HOOKENTRY fnarm(pRefData, pcrf)
      ENTRY    pRefData - Pointer to reference data
              pcrf    - Pointer to client register frame
      EXIT    None
      USES    EAX, ECX, EDX, FS, GS, Flags
      CONTEXT  DOS session-task</pre>
 
 
Success If the function was successful, it returns nothing.
 
Failure If either ''HookHandle''or ''VDMHandle''is invalid, or if the hook is already armed, a system halt occurs.
 
 
 
 
 
=== VDHArmSTIHook - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: Any STI hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager.
 
Notes: Interrupt re-enabling detection is performed when the DOS session runs with IOPL = 0. This causes any instructions that might modify the interrupt flag to fault.
 
 
 
 
 
=== VDHArmSTIHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHArmTimerHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function sets a timer handler to be called after a specified period of time has elapsed. The handler is called only once.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Timer hook handle */
ULONG    Duration;    /*  Duration of the timeout in milliseconds */
HVDM    VDMHandle;  /*  DOS session handle */
 
VDHArmTimerHook(HookHandle, Duration, VDMHandle);</pre>
 
 
 
 
=== VDHArmTimerHook - Format ===
 
This function sets a timer handler to be called after a specified period of time has elapsed. The handler is called only once.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Timer hook handle */
ULONG    Duration;    /*  Duration of the timeout in milliseconds */
HVDM    VDMHandle;  /*  DOS session handle */
 
VDHArmTimerHook(HookHandle, Duration, VDMHandle);</pre>
 
 
 
 
=== VDHArmTimerHook Parameter - HookHandle ===
 
'''HookHandle'''(HHOOK) Timer hook handle.
 
 
 
 
 
=== VDHArmTimerHook Parameter - Duration ===
 
'''Duration'''(ULONG) Timer duration in milliseconds.
 
 
 
 
 
=== VDHArmTimerHook Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) DOS session handle.
 
Possible values are:
 
DOS Session Handle or 0 When the specified time duration expires, a local context hook is automatically armed by using the specified ''HookHandle''.
 
VDH_TIMER_GLOBAL_CONTEXT When the specified time duration expires, a global context hook is automatically armed by using the specified ''HookHandle''.
 
VDH_TIMER_INTERRUPT_HOOK When the specified time duration expires, the timer hook specified by ''HookHandle''is called at interrupt time.
 
Hook routine interface:
 
<pre class="western">VOID HOOKENTRY  pfn(pRefData)
    ENTRY      pRefData - Pointer to reference data
    EXIT      None
    CONTEXT    Interrupt
Note:  This hook routine interface is for interrupt-type hooks only.
      For context-type hooks, see hook routine interface listed under
      VDHArmContextHook.</pre>
 
 
 
 
 
 
=== VDHArmTimerHook - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If either ''Duration''or ''HookHandle''is invalid or the hook is already armed, a system halt occurs.
 
 
 
 
 
=== VDHArmTimerHook - Parameters ===
 
'''HookHandle'''(HHOOK) Timer hook handle.
 
'''Duration'''(ULONG) Timer duration in milliseconds.
 
'''VDMHandle'''(HVDM) DOS session handle.
 
Possible values are:
 
DOS Session Handle or 0 When the specified time duration expires, a local context hook is automatically armed by using the specified ''HookHandle''.
 
VDH_TIMER_GLOBAL_CONTEXT When the specified time duration expires, a global context hook is automatically armed by using the specified ''HookHandle''.
 
VDH_TIMER_INTERRUPT_HOOK When the specified time duration expires, the timer hook specified by ''HookHandle''is called at interrupt time.
 
Hook routine interface:
 
<pre class="western">VOID HOOKENTRY  pfn(pRefData)
    ENTRY      pRefData - Pointer to reference data
    EXIT      None
    CONTEXT    Interrupt
Note:  This hook routine interface is for interrupt-type hooks only.
      For context-type hooks, see hook routine interface listed under
      VDHArmContextHook.</pre>
 
 
Success If the function is successful, it returns nothing.
 
Failure If either ''Duration''or ''HookHandle''is invalid or the hook is already armed, a system halt occurs.
 
 
 
 
 
=== VDHArmTimerHook - Purpose ===
 
Context Issues: This function can be called in the initialization, task, or interrupt context.
 
DOS Session Terminations: Any timer hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager at DOS session termination.
 
Notes: If type VDH_TIMER_INTERRUPT_HOOK, the timer handler cannot block since it executes at physical interrupt time.
 
 
 
 
 
=== VDHArmTimerHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHArmVPMBPHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function obtains the address of the DOS session's protected-mode breakpoint allocated by a previous call to ''VDHAllocHook''with the VDH_BP_ HOOK flag.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle allocated with VDHAllocHook */
FPFN    rc;
 
rc = VDHArmVPMBPHook(HookHandle);</pre>
 
 
 
 
=== VDHArmVPMBPHook - Format ===
 
This function obtains the address of the DOS session's protected-mode breakpoint allocated by a previous call to ''VDHAllocHook''with the VDH_BP_ HOOK flag.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle allocated with VDHAllocHook */
FPFN    rc;
 
rc = VDHArmVPMBPHook(HookHandle);</pre>
 
 
 
 
=== VDHArmVPMBPHook Parameter - HookHandle ===
 
'''HookHandle'''(HHOOK) Hook handle allocated with ''VDHAllocHook''.
 
The hook routine interface:
 
<pre class="western"> VOID HOOKENTRY fnarm(pRefData, pcrf)
      ENTRY    pRefData - Pointer to hook-specific reference data
              pcrf    - Pointer to client register frame
      EXIT    None
      CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHArmVPMBPHook Return Value - rc ===
 
'''rc'''(FPFN) - returns
 
Success If the function is successful, it returns a DOS session protected- mode breakpoint address.
 
Failure If ''HookHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHArmVPMBPHook - Parameters ===
 
'''HookHandle'''(HHOOK) Hook handle allocated with ''VDHAllocHook''.
 
The hook routine interface:
 
<pre class="western"> VOID HOOKENTRY fnarm(pRefData, pcrf)
      ENTRY    pRefData - Pointer to hook-specific reference data
              pcrf    - Pointer to client register frame
      EXIT    None
      CONTEXT  DOS session-task</pre>
 
 
'''rc'''(FPFN) - returns
 
Success If the function is successful, it returns a DOS session protected- mode breakpoint address.
 
Failure If ''HookHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHArmVPMBPHook - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Unlike other hooks, breakpoint hooks are armed until explicitly disarmed by a call to ''VDHFreeHook''. When the breakpoint address is executed from DOS session protected mode, the hook function is called. Any changes made to the client register frame cause the corresponding registers to take on these values after returning to the DOS session. The ''p''parameter in the hook routine points to the ''RefDataSize''bytes of data allocated by ''VDHAllocHook''.
 
''VDHArmVPMBPHook''provides a raw breakpoint service. On entry to the arm hook function, the client's CS:EIP is randomly set. It is therefore crucial that the virtual device driver's hook handler sets the CS:EIP to a valid address . Typically, the CS:EIP is retrieved from the client's stack through the use of ''VDHPopStack'', which is a low-level service. Appropriate care should be exercised to ensure that the client's CS:EIP and stack remain valid.
 
The breakpoint address returned will be valid for all DPMI clients within the DOS session. The breakpoint address may be placed in the DPMI application's IDT (see [[01066.htm|VDHSetVPMIntVector]]), but will have to be rehooked each time a DPMI task starts (see [[00594.htm|VDHInstallUserHook]]).
 
There must be a protected-mode DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHArmVPMBPHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHBeginUseVPMStack ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used to switch to the DOS session's protected-mode stack for hardware interrupts, exceptions, and so forth. This service can be called repeatedly, but only the first call will switch stacks. Subsequent calls increment use, count but remain on the VPM stack.
 
<pre class="western">#include mvdm.h
 
VOID    ;
 
VDHBeginUseVPMStack();</pre>
 
 
 
 
=== VDHBeginUseVPMStack - Format ===
 
This function is used to switch to the DOS session's protected-mode stack for hardware interrupts, exceptions, and so forth. This service can be called repeatedly, but only the first call will switch stacks. Subsequent calls increment use, count but remain on the VPM stack.
 
<pre class="western">#include mvdm.h
 
VOID    ;
 
VDHBeginUseVPMStack();</pre>
 
 
 
 
=== VDHBeginUseVPMStack Parameter - ===
 
None.
 
 
 
 
 
=== VDHBeginUseVPMStack - Return Value ===
 
None.
 
 
 
 
 
=== VDHBeginUseVPMStack - Parameters ===
 
None.
 
None.
 
 
 
 
 
=== VDHBeginUseVPMStack - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: There must be a DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHBeginUseVPMStack - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCallOutDMA ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used by the virtual DMA device driver (VDMA) to check how much DMA transfer has been completed, and to copy the contents from the temporary buffer to the DOS area.
 
If a virtual device driver owns a DMA channel, it must call the virtual DMA device driver for those interrupts that occur when a DMA request is pending on that channel. This service also indicates when the DOS session is done with the channel so that the channel can be given to another waiting DOS session.
 
<pre class="western">#include mvdm.h
 
VOID    ;
 
VDHCallOutDMA();</pre>
 
 
 
 
=== VDHCallOutDMA - Format ===
 
This function is used by the virtual DMA device driver (VDMA) to check how much DMA transfer has been completed, and to copy the contents from the temporary buffer to the DOS area.
 
If a virtual device driver owns a DMA channel, it must call the virtual DMA device driver for those interrupts that occur when a DMA request is pending on that channel. This service also indicates when the DOS session is done with the channel so that the channel can be given to another waiting DOS session.
 
<pre class="western">#include mvdm.h
 
VOID    ;
 
VDHCallOutDMA();</pre>
 
 
 
 
=== VDHCallOutDMA Parameter - ===
 
None.
 
 
 
 
 
=== VDHCallOutDMA - Return Value ===
 
None.
 
 
 
 
 
=== VDHCallOutDMA - Parameters ===
 
None.
 
None.
 
 
 
 
 
=== VDHCallOutDMA - Purpose ===
 
Context Issues: This function can be called in any context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHCallOutDMA - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHChangeVPMIF ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function changes the virtual Interrupt Flag (IF) that enables or disables protected-mode interrupts. This change is reflected in a bit in the ''flVDMStatus''kernel variable (see &quot;Notes&quot; under Purpose). If the STI hooks are waiting and interrupts are enabled, the hooks are called.
 
<pre class="western">#include mvdm.h
 
BOOL    SetIFFlag;  /*  Indicates whether to turn the IF flag on or off */
BOOL    rc;
 
rc = VDHChangeVPMIF(SetIFFlag);</pre>
 
 
 
 
=== VDHChangeVPMIF - Format ===
 
This function changes the virtual Interrupt Flag (IF) that enables or disables protected-mode interrupts. This change is reflected in a bit in the ''flVDMStatus''kernel variable (see &quot;Notes&quot; under Purpose). If the STI hooks are waiting and interrupts are enabled, the hooks are called.
 
<pre class="western">#include mvdm.h
 
BOOL    SetIFFlag;  /*  Indicates whether to turn the IF flag on or off */
BOOL    rc;
 
rc = VDHChangeVPMIF(SetIFFlag);</pre>
 
 
 
 
=== VDHChangeVPMIF Parameter - SetIFFlag ===
 
'''SetIFFlag'''(BOOL) Indicates whether to turn the IF flag ON or OFF. If nonzero, set IF flag to 1 (one). If zero, set IF flag to 0 (zero).
 
 
 
 
 
=== VDHChangeVPMIF Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure Not applicable to this function.
 
 
 
 
 
=== VDHChangeVPMIF - Parameters ===
 
'''SetIFFlag'''(BOOL) Indicates whether to turn the IF flag ON or OFF. If nonzero, set IF flag to 1 (one). If zero, set IF flag to 0 (zero).
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure Not applicable to this function.
 
 
 
 
 
=== VDHChangeVPMIF - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: The ''flVDMStatus''kernel variable is exported from the kernel. Any virtual device driver can refer to it directly. ''flVDMStatus''is a DD-sized variable that contains various DOS session status flags relating to protected mode and the DOS Protected Mode Interface (DPMI).
 
The ''flVDMStatus''flags indicate:
 
*DPMI was initialized (protected mode was enabled) <br />*16-bit or 32-bit <br />*The current execution mode (V86 or protected)
 
These flags and their values are:
 
<pre class="western">  VDM_STATUS_VPM_32        0x00000001      /* 32-bit DPMI application  */
  VDM_STATUS_VPM_APP        0x00000002      /* DPMI application started  */
  VDM_STATUS_VPM_EXEC      0x00000004      /* In DOS session protected mode*/
  VDM_STATUS_VPM_IF_FLAG    0x00000010      /* Virtual IF flag          */
  VDM_STATUS_VPM_PERM      0x00000080      /* Protected mode allowed?  */
  VDM_STATUS_VPM_XDOS      0x00000100      /* DOS API extension active? */</pre>
 
 
 
 
=== VDHChangeVPMIF - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCheckPagePerm ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function checks Ring 3 page permissions for a range of pages. This service fails if a Ring 3 client faults on any of the pages that have been checked.
 
<pre class="western">#include mvdm.h
 
ULONG    BasePage;  /*  Base virtual page number */
PVOID    Reserved;  /*  Reserved; must be set to zero */
ULONG    NumPages;  /*  Number of pages to verify */
ULONG    Flag;      /*  Flag */
BOOL    rc;
 
rc = VDHCheckPagePerm(BasePage, Reserved,
      NumPages, Flag);</pre>
 
 
 
 
=== VDHCheckPagePerm - Format ===
 
This function checks Ring 3 page permissions for a range of pages. This service fails if a Ring 3 client faults on any of the pages that have been checked.
 
<pre class="western">#include mvdm.h
 
ULONG    BasePage;  /*  Base virtual page number */
PVOID    Reserved;  /*  Reserved; must be set to zero */
ULONG    NumPages;  /*  Number of pages to verify */
ULONG    Flag;      /*  Flag */
BOOL    rc;
 
rc = VDHCheckPagePerm(BasePage, Reserved,
      NumPages, Flag);</pre>
 
 
 
 
=== VDHCheckPagePerm Parameter - BasePage ===
 
'''BasePage'''(ULONG) Base virtual page number.
 
 
 
 
 
=== VDHCheckPagePerm Parameter - Reserved ===
 
'''Reserved'''(PVOID) Reserved. Must be set to ''0''.
 
 
 
 
 
=== VDHCheckPagePerm Parameter - NumPages ===
 
'''NumPages'''(ULONG) Number of pages to verify.
 
 
 
 
 
=== VDHCheckPagePerm Parameter - Flag ===
 
'''Flag'''(ULONG) Values are:
 
VPMPG_U Are the pages user-accessible? <br />VPMPG_W Are the pages writable? <br />VPMPG_R Are the pages readable (valid)? <br />VPMPG_X Are the pages executable?
 
 
 
 
 
=== VDHCheckPagePerm Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0.
 
 
 
 
 
=== VDHCheckPagePerm - Parameters ===
 
'''BasePage'''(ULONG) Base virtual page number.
 
'''Reserved'''(PVOID) Reserved. Must be set to ''0''.
 
'''NumPages'''(ULONG) Number of pages to verify.
 
'''Flag'''(ULONG) Values are:
 
VPMPG_U Are the pages user-accessible? <br />VPMPG_W Are the pages writable? <br />VPMPG_R Are the pages readable (valid)? <br />VPMPG_X Are the pages executable?
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0.
 
 
 
 
 
=== VDHCheckPagePerm - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHCheckPagePerm - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCheckVPMIntVector ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns a nonzero value if the application protected-mode interrupt vector is set.
 
<pre class="western">#include mvdm.h
 
ULONG    Vector;  /*  Interrupt vector number */
BOOL    rc;
 
rc = VDHCheckVPMIntVector(Vector);</pre>
 
 
 
 
=== VDHCheckVPMIntVector - Format ===
 
This function returns a nonzero value if the application protected-mode interrupt vector is set.
 
<pre class="western">#include mvdm.h
 
ULONG    Vector;  /*  Interrupt vector number */
BOOL    rc;
 
rc = VDHCheckVPMIntVector(Vector);</pre>
 
 
 
 
=== VDHCheckVPMIntVector Parameter - Vector ===
 
'''Vector'''(ULONG) Interrupt vector number.
 
 
 
 
 
=== VDHCheckVPMIntVector Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful it returns a nonzero value.
 
Failure If there is no user-registered interrupt handler for the interrupt in ''Vector'', the function returns 0 (zero).
 
 
 
 
 
=== VDHCheckVPMIntVector - Parameters ===
 
'''Vector'''(ULONG) Interrupt vector number.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful it returns a nonzero value.
 
Failure If there is no user-registered interrupt handler for the interrupt in ''Vector'', the function returns 0 (zero).
 
 
 
 
 
=== VDHCheckVPMIntVector - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: There must be a DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHCheckVPMIntVector - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHClearVIRR ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function clears the virtual Interrupt Request Register (IRR) in the Virtual Programmable Interrupt Controller (VPIC) of the specified DOS session for the IRQ specified. The simulation of interrupts to the specified DOS session is stopped on this IRQ level.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  DOS session handle */
HIRQ    IRQHandle;  /*  IRQ handle from VDHOpenVIRQ */
 
VDHClearVIRR(VDMHandle, IRQHandle);</pre>
 
 
 
 
=== VDHClearVIRR - Format ===
 
This function clears the virtual Interrupt Request Register (IRR) in the Virtual Programmable Interrupt Controller (VPIC) of the specified DOS session for the IRQ specified. The simulation of interrupts to the specified DOS session is stopped on this IRQ level.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  DOS session handle */
HIRQ    IRQHandle;  /*  IRQ handle from VDHOpenVIRQ */
 
VDHClearVIRR(VDMHandle, IRQHandle);</pre>
 
 
 
 
=== VDHClearVIRR Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
 
 
 
 
=== VDHClearVIRR Parameter - IRQHandle ===
 
'''IRQHandle'''(HIRQ) IRQ handle from ''VDHOpenVIRQ''.
 
 
 
 
 
=== VDHClearVIRR - Return Value ===
 
Success If the function was successful, it returns nothing.
 
Failure If either of the parameters is invalid, a system halt occurs.
 
 
 
 
 
=== VDHClearVIRR - Parameters ===
 
'''VDMHandle'''(HVDM) DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
'''IRQHandle'''(HIRQ) IRQ handle from ''VDHOpenVIRQ''.
 
Success If the function was successful, it returns nothing.
 
Failure If either of the parameters is invalid, a system halt occurs.
 
 
 
 
 
=== VDHClearVIRR - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHClearVIRR - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHClose ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function closes a file or device that was opened with ''VDHOpen''.
 
<pre class="western">#include mvdm.h
 
HFILE    FileHandle;  /*  Handle to the file or device to close */
 
VDHClose(FileHandle);</pre>
 
 
 
 
=== VDHClose - Format ===
 
This function closes a file or device that was opened with ''VDHOpen''.
 
<pre class="western">#include mvdm.h
 
HFILE    FileHandle;  /*  Handle to the file or device to close */
 
VDHClose(FileHandle);</pre>
 
 
 
 
=== VDHClose Parameter - FileHandle ===
 
'''FileHandle'''(HFILE) Handle (from ''VDHOpen'') to the file or device to close.
 
 
 
 
 
=== VDHClose - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''FileHandle''is invalid or if the DOS session is not in the DOS session-task context, a system halt occurs.
 
 
 
 
 
=== VDHClose - Parameters ===
 
'''FileHandle'''(HFILE) Handle (from ''VDHOpen'') to the file or device to close.
 
Success If the function is successful, it returns nothing.
 
Failure If ''FileHandle''is invalid or if the DOS session is not in the DOS session-task context, a system halt occurs.
 
 
 
 
 
=== VDHClose - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: Any handles opened by the virtual device driver for the terminating DOS session must be closed.
 
 
 
 
 
=== VDHClose - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCloseVDD ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function closes a virtual device driver/virtual device driver (VDD/VDD ) Inter-Device-Driver Communication (IDC) session that was opened with ''VDHOpenVDD''.
 
<pre class="western">#include mvdm.h
 
HVDD    VDDHandle;  /*  Handle to the file or device to close */
 
VDHCloseVDD(VDDHandle);</pre>
 
 
 
 
=== VDHCloseVDD - Format ===
 
This function closes a virtual device driver/virtual device driver (VDD/VDD ) Inter-Device-Driver Communication (IDC) session that was opened with ''VDHOpenVDD''.
 
<pre class="western">#include mvdm.h
 
HVDD    VDDHandle;  /*  Handle to the file or device to close */
 
VDHCloseVDD(VDDHandle);</pre>
 
 
 
 
=== VDHCloseVDD Parameter - VDDHandle ===
 
'''VDDHandle'''(HVDD) Handle (from ''VDHOpenVDD'') to the virtual device driver to close.
 
 
 
 
 
=== VDHCloseVDD - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''VDMHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHCloseVDD - Parameters ===
 
'''VDDHandle'''(HVDD) Handle (from ''VDHOpenVDD'') to the virtual device driver to close.
 
Success If the function is successful, it returns nothing.
 
Failure If ''VDMHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHCloseVDD - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: If a virtual device driver has a VDD/VDD session for a particular DOS session, that session is closed when the DOS session terminates.
 
Notes: This service is used to close the type of VDD/VDD connections, which are temporary or are on a per-DOS session basis.
 
 
 
 
 
=== VDHCloseVDD - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCloseVIRQ ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function closes the virtual IRQ handle passed to it.
 
<pre class="western">#include mvdm.h
 
HIRQ    IRQHandl;  /*  Handle of the virtual device driver to close */
 
VDHCloseVIRQ(IRQHandl);</pre>
 
 
 
 
=== VDHCloseVIRQ - Format ===
 
This function closes the virtual IRQ handle passed to it.
 
<pre class="western">#include mvdm.h
 
HIRQ    IRQHandl;  /*  Handle of the virtual device driver to close */
 
VDHCloseVIRQ(IRQHandl);</pre>
 
 
 
 
=== VDHCloseVIRQ Parameter - IRQHandl ===
 
'''IRQHandl'''(HIRQ) Handle to the IRQ (from ''VDHOpenVIRQ'') to close.
 
 
 
 
 
=== VDHCloseVIRQ - Return Value ===
 
Success If the function was successful, it returns nothing.
 
Failure If ''IRQHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHCloseVIRQ - Parameters ===
 
'''IRQHandl'''(HIRQ) Handle to the IRQ (from ''VDHOpenVIRQ'') to close.
 
Success If the function was successful, it returns nothing.
 
Failure If ''IRQHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHCloseVIRQ - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHCloseVIRQ - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCopyMem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function copies memory from one user linear address to another.
 
<pre class="western">#include mvdm.h
 
PVOID    Source;      /*  Address of the data to copy */
PVOID    Destination;  /*  Address to copy the data to */
ULONG    NumBytes;    /*  Number of bytes to copy */
 
VDHCopyMem(Source, Destination, NumBytes);</pre>
 
 
 
 
=== VDHCopyMem - Format ===
 
This function copies memory from one user linear address to another.
 
<pre class="western">#include mvdm.h
 
PVOID    Source;      /*  Address of the data to copy */
PVOID    Destination;  /*  Address to copy the data to */
ULONG    NumBytes;    /*  Number of bytes to copy */
 
VDHCopyMem(Source, Destination, NumBytes);</pre>
 
 
 
 
=== VDHCopyMem Parameter - Source ===
 
'''Source'''(PVOID) Address of the source data to be copied.
 
 
 
 
 
=== VDHCopyMem Parameter - Destination ===
 
'''Destination'''(PVOID) Address to which the data is to be copied.
 
 
 
 
 
=== VDHCopyMem Parameter - NumBytes ===
 
'''NumBytes'''(ULONG) Number of bytes to copy.
 
 
 
 
 
=== VDHCopyMem - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''NumBytes''is 0 (zero), a system halt occurs.
 
 
 
 
 
=== VDHCopyMem - Parameters ===
 
'''Source'''(PVOID) Address of the source data to be copied.
 
'''Destination'''(PVOID) Address to which the data is to be copied.
 
'''NumBytes'''(ULONG) Number of bytes to copy.
 
Success If the function is successful, it returns nothing.
 
Failure If ''NumBytes''is 0 (zero), a system halt occurs.
 
 
 
 
 
=== VDHCopyMem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Protection faults are handled as if a user application had performed the access. Therefore, writing to an invalid page causes a virtual device driver page fault handler to gain control. If there is no virtual device driver fault handler, a &quot;don't care&quot; page is mapped in at the faulting linear address.
 
Note that touching invalid pages is allowed only in the context of the DOS session. A virtual device driver cannot touch invalid pages through the HVDM (DOS session Handle) alias region if it is not in the context of that DOS session. A virtual device driver that violates this rule causes a system halt.
 
This function yields the CPU if it is necessary to ensure that the thread dispatch latency limit is not exceeded. This function also supports overlapping linear regions. However, the results are undefined when copying between regions with aliases (through ''VDHMapPages'') to the same physical page.
 
If necessary, ''VDHLockMem''is used to ensure that the status of the source and destination linear ranges does not change. This is required only if the source and destination ranges are in private DOS session memory (accessed through the HVDM), and the call to ''VDHCopyMem''is made in the context of some other process.
 
 
 
 
 
=== VDHCopyMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCreateBlockPool ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function creates a pool of memory blocks of a specified size. The blocks are allocated from the system area so that the block addresses are valid in all process contexts.
 
<pre class="western">#include mvdm.h
 
ULONG    BlockSize;  /*  Size of block to initialize (in bytes) */
ULONG    OptionFlag;  /*  Allocation options bit flag */
HBLOCK    rc;
 
rc = VDHCreateBlockPool(BlockSize, OptionFlag);</pre>
 
 
 
 
=== VDHCreateBlockPool - Format ===
 
This function creates a pool of memory blocks of a specified size. The blocks are allocated from the system area so that the block addresses are valid in all process contexts.
 
<pre class="western">#include mvdm.h
 
ULONG    BlockSize;  /*  Size of block to initialize (in bytes) */
ULONG    OptionFlag;  /*  Allocation options bit flag */
HBLOCK    rc;
 
rc = VDHCreateBlockPool(BlockSize, OptionFlag);</pre>
 
 
 
 
=== VDHCreateBlockPool Parameter - BlockSize ===
 
'''BlockSize'''(ULONG) Size of block to initialize (in bytes).
 
 
 
 
 
=== VDHCreateBlockPool Parameter - OptionFlag ===
 
'''OptionFlag'''(ULONG) Allocation options bit flag. Possible value:
 
VDHCBP_SWAPPABLE Blocks are allocated from the swappable heap. Otherwise, blocks are allocated from the fixed heap and can be accessed at hardware interrupt time.
 
 
 
 
 
=== VDHCreateBlockPool Return Value - rc ===
 
'''rc'''(HBLOCK) - returns
 
Success If the function is successful, it returns a handle to the pool of memory blocks.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''OptionFlag''is invalid, or if ''BlockSize''is equal to 0 (zero), a system halt occurs.
 
 
 
 
 
=== VDHCreateBlockPool - Parameters ===
 
'''BlockSize'''(ULONG) Size of block to initialize (in bytes).
 
'''OptionFlag'''(ULONG) Allocation options bit flag. Possible value:
 
VDHCBP_SWAPPABLE Blocks are allocated from the swappable heap. Otherwise, blocks are allocated from the fixed heap and can be accessed at hardware interrupt time.
 
'''rc'''(HBLOCK) - returns
 
Success If the function is successful, it returns a handle to the pool of memory blocks.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''OptionFlag''is invalid, or if ''BlockSize''is equal to 0 (zero), a system halt occurs.
 
 
 
 
 
=== VDHCreateBlockPool - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: Any block pools allocated by a virtual device driver for use by the terminating DOS session is freed by using ''VDHDestroyBlockPool''.
 
 
 
 
 
=== VDHCreateBlockPool - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCreateSel ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function creates a GDT selector that maps a linear range. This service is used to create a 16:16 pointer, which is passed to a 16-bit physical device driver.
 
<pre class="western">#include mvdm.h
 
PVOID    LinearAddress;  /*  Linear address of the start of the buffer */
ULONG    BufferSize;    /*  Size of the buffer in bytes */
SEL      rc;
 
rc = VDHCreateSel(LinearAddress, BufferSize);</pre>
 
 
 
 
=== VDHCreateSel - Format ===
 
This function creates a GDT selector that maps a linear range. This service is used to create a 16:16 pointer, which is passed to a 16-bit physical device driver.
 
<pre class="western">#include mvdm.h
 
PVOID    LinearAddress;  /*  Linear address of the start of the buffer */
ULONG    BufferSize;    /*  Size of the buffer in bytes */
SEL      rc;
 
rc = VDHCreateSel(LinearAddress, BufferSize);</pre>
 
 
 
 
=== VDHCreateSel Parameter - LinearAddress ===
 
'''LinearAddress'''(PVOID) Linear address of the beginning of the buffer.
 
 
 
 
 
=== VDHCreateSel Parameter - BufferSize ===
 
'''BufferSize'''(ULONG) Size of the buffer in bytes. The expected range is 0- 65535 with 0 interpreted as 65536.
 
 
 
 
 
=== VDHCreateSel Return Value - rc ===
 
'''rc'''(SEL) - returns
 
Success If the function is successful, it returns a nonzero selector value such that SELECTOR:0 points to the first byte of the linear range.
 
Failure If ''BufferSize''is greater than 65535 or if there are no more selectors available, a system halt occurs.
 
 
 
 
 
=== VDHCreateSel - Parameters ===
 
'''LinearAddress'''(PVOID) Linear address of the beginning of the buffer.
 
'''BufferSize'''(ULONG) Size of the buffer in bytes. The expected range is 0- 65535 with 0 interpreted as 65536.
 
'''rc'''(SEL) - returns
 
Success If the function is successful, it returns a nonzero selector value such that SELECTOR:0 points to the first byte of the linear range.
 
Failure If ''BufferSize''is greater than 65535 or if there are no more selectors available, a system halt occurs.
 
 
 
 
 
=== VDHCreateSel - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: Any selectors created to map memory in the terminating DOS session must be destroyed with ''VDHDestroySel''. The virtual device driver must ensure that any physical device driver that was given these selectors is finished with them.
 
Notes: The linear address must be in system memory. To create a 16:16 pointer to a DOS session address (in the 0 to 1MB+64KB range), use the HVDM (DOS session handle) alias linear address. ''VDHDestroySel''must be called when finished with this pointer.
 
 
 
 
 
=== VDHCreateSel - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCreateSem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used to create an event or mutex semaphore.
 
<pre class="western">#include mvdm.h
 
PHVDHSEM    SemHandlePointer;  /*  Semaphore handle address */
ULONG      SemType;          /*  Type of semaphore of create */
BOOL        rc;
 
rc = VDHCreateSem(SemHandlePointer, SemType);</pre>
 
 
 
 
=== VDHCreateSem - Format ===
 
This function is used to create an event or mutex semaphore.
 
<pre class="western">#include mvdm.h
 
PHVDHSEM    SemHandlePointer;  /*  Semaphore handle address */
ULONG      SemType;          /*  Type of semaphore of create */
BOOL        rc;
 
rc = VDHCreateSem(SemHandlePointer, SemType);</pre>
 
 
 
 
=== VDHCreateSem Parameter - SemHandlePointer ===
 
'''SemHandlePointer'''(PHVDHSEM) Semaphore handle address.
 
 
 
 
 
=== VDHCreateSem Parameter - SemType ===
 
'''SemType'''(ULONG) Type of semaphore to create.
 
Values are:
 
VDH_EVENTSEM Event semaphore <br />VDH_MUTEXSEM Mutex semaphore
 
 
 
 
 
=== VDHCreateSem Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value and places a handle to the semaphore in ''SemHandlePointer''.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. An invalid semaphore type causes a system halt to occur.
 
 
 
 
 
=== VDHCreateSem - Parameters ===
 
'''SemHandlePointer'''(PHVDHSEM) Semaphore handle address.
 
'''SemType'''(ULONG) Type of semaphore to create.
 
Values are:
 
VDH_EVENTSEM Event semaphore <br />VDH_MUTEXSEM Mutex semaphore
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value and places a handle to the semaphore in ''SemHandlePointer''.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. An invalid semaphore type causes a system halt to occur.
 
 
 
 
 
=== VDHCreateSem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: These semaphores are global and are not attached to a specific DOS session. If a virtual device driver maintains semaphores on a per-DOS session basis, it destroys the semaphores by using ''VDHDestroySem''when the DOS session they are associated with is terminated.
 
 
 
 
 
=== VDHCreateSem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDecodeProperty ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function decodes the specified format of a property string. (See Notes )
 
<pre class="western">#include mvdm.h
 
PPSZ      ppProperty;      /*  Pointer to a pointer to property string */
PULONG    StartNumberPtr;  /*  Location to return the starting number */
PULONG    EndNumberPtr;    /*  Location to return the ending number */
ULONG    BaseFlag;        /*  Flag indicating the numeric base to use */
BOOL      rc;
 
rc = VDHDecodeProperty(ppProperty, StartNumberPtr,
      EndNumberPtr, BaseFlag);</pre>
 
 
 
 
=== VDHDecodeProperty - Format ===
 
This function decodes the specified format of a property string. (See Notes )
 
<pre class="western">#include mvdm.h
 
PPSZ      ppProperty;      /*  Pointer to a pointer to property string */
PULONG    StartNumberPtr;  /*  Location to return the starting number */
PULONG    EndNumberPtr;    /*  Location to return the ending number */
ULONG    BaseFlag;        /*  Flag indicating the numeric base to use */
BOOL      rc;
 
rc = VDHDecodeProperty(ppProperty, StartNumberPtr,
      EndNumberPtr, BaseFlag);</pre>
 
 
 
 
=== VDHDecodeProperty Parameter - ppProperty ===
 
'''ppProperty'''(PPSZ) A pointer to a pointer to the property string to be decoded.
 
 
 
 
 
=== VDHDecodeProperty Parameter - StartNumberPtr ===
 
'''StartNumberPtr'''(PULONG) Location for storing the returned starting number.
 
 
 
 
 
=== VDHDecodeProperty Parameter - EndNumberPtr ===
 
'''EndNumberPtr'''(PULONG) Location for storing the returned ending number.
 
 
 
 
 
=== VDHDecodeProperty Parameter - BaseFlag ===
 
'''BaseFlag'''(ULONG) Flag indicating which numeric base to use:
 
VDH_DP_DECIMAL Decimal <br />VDH_DP_HEX Hex
 
 
 
 
 
=== VDHDecodeProperty Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value and the ''ppProperty''pointer is modified to point to the next range in the property string. ''StartNumberPtr''and ''EndNumberPtr''will have the range values. ''ppProperty''is returned NULL after processing the last range.
 
Failure If the function fails, it returns 0, indicating an invalid parameter. If ''BaseFlag''contains an invalid value or if ''ppProperty''is NULL, a system halt occurs.
 
 
 
 
 
=== VDHDecodeProperty - Parameters ===
 
'''ppProperty'''(PPSZ) A pointer to a pointer to the property string to be decoded.
 
'''StartNumberPtr'''(PULONG) Location for storing the returned starting number.
 
'''EndNumberPtr'''(PULONG) Location for storing the returned ending number.
 
'''BaseFlag'''(ULONG) Flag indicating which numeric base to use:
 
VDH_DP_DECIMAL Decimal <br />VDH_DP_HEX Hex
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value and the ''ppProperty''pointer is modified to point to the next range in the property string. ''StartNumberPtr''and ''EndNumberPtr''will have the range values. ''ppProperty''is returned NULL after processing the last range.
 
Failure If the function fails, it returns 0, indicating an invalid parameter. If ''BaseFlag''contains an invalid value or if ''ppProperty''is NULL, a system halt occurs.
 
 
 
 
 
=== VDHDecodeProperty - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: If a single value is found, ''EndNumberPtr''is a -1. All the numbers are decoded in the specified base. A negative sign is used only as range delimiter. Numbers cannot have more than eight digits or a failure is returned. If this service returns Failure, it is still possible that the contents of ''StartNumberPtr''or ''EndNumberPtr''might have changed.
 
Because pointers passed are from a virtual device driver (not a user), there is no verification of addresses. Bad pointers result in page faults.
 
This function decodes the specified format of a property string as shown below:
 
<pre class="western">String Syntax = &quot;N1-N2,N3-N4,N5,N6-N7,...&quot;</pre>
Notice that N''x''are valid numbers in a specified base.
 
 
 
 
 
=== VDHDecodeProperty - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDestroyBlockPool ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function releases a memory block pool.
 
<pre class="western">#include mvdm.h
 
HBLOCK    PoolHandle;  /*  Handle to the memory block pool to release */
HBLOCK    rc;
 
rc = VDHDestroyBlockPool(PoolHandle);</pre>
 
 
 
 
=== VDHDestroyBlockPool - Format ===
 
This function releases a memory block pool.
 
<pre class="western">#include mvdm.h
 
HBLOCK    PoolHandle;  /*  Handle to the memory block pool to release */
HBLOCK    rc;
 
rc = VDHDestroyBlockPool(PoolHandle);</pre>
 
 
 
 
=== VDHDestroyBlockPool Parameter - PoolHandle ===
 
'''PoolHandle'''(HBLOCK) Handle to the memory block pool to release.
 
 
 
 
 
=== VDHDestroyBlockPool Return Value - rc ===
 
'''rc'''(HBLOCK) - returns
 
Success If the function was successful, it returns nothing.
 
Failure An invalid memory block pool handle causes a system halt to occur.
 
 
 
 
 
=== VDHDestroyBlockPool - Parameters ===
 
'''PoolHandle'''(HBLOCK) Handle to the memory block pool to release.
 
'''rc'''(HBLOCK) - returns
 
Success If the function was successful, it returns nothing.
 
Failure An invalid memory block pool handle causes a system halt to occur.
 
 
 
 
 
=== VDHDestroyBlockPool - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHDestroyBlockPool - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDestroySel ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function destroys a GDT selector created by ''VDHCreateSel''.
 
<pre class="western">#include mvdm.h
 
SEL    GDTSelector;  /*  GDT selector to destroy */
 
VDHDestroySel(GDTSelector);</pre>
 
 
 
 
=== VDHDestroySel - Format ===
 
This function destroys a GDT selector created by ''VDHCreateSel''.
 
<pre class="western">#include mvdm.h
 
SEL    GDTSelector;  /*  GDT selector to destroy */
 
VDHDestroySel(GDTSelector);</pre>
 
 
 
 
=== VDHDestroySel Parameter - GDTSelector ===
 
'''GDTSelector'''(SEL) GDT selector to be destroyed.
 
 
 
 
 
=== VDHDestroySel - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''GDTSelector''was not created by ''VDHCreateSel'', a system halt occurs.
 
 
 
 
 
=== VDHDestroySel - Parameters ===
 
'''GDTSelector'''(SEL) GDT selector to be destroyed.
 
Success If the function is successful, it returns nothing.
 
Failure If ''GDTSelector''was not created by ''VDHCreateSel'', a system halt occurs.
 
 
 
 
 
=== VDHDestroySel - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: All selectors created with ''VDHCreateSel''that map the terminating DOS session must be destroyed.
 
 
 
 
 
=== VDHDestroySel - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDestroySem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function destroys a semaphore previously created with ''VDHCreateSem''. The semaphore must be posted or unowned before calling this service.
 
<pre class="western">#include mvdm.h
 
HVDHSEM    SemHandle;  /*  Semaphore handle to destroy */
 
VDHDestroySem(SemHandle);</pre>
 
 
 
 
=== VDHDestroySem - Format ===
 
This function destroys a semaphore previously created with ''VDHCreateSem''. The semaphore must be posted or unowned before calling this service.
 
<pre class="western">#include mvdm.h
 
HVDHSEM    SemHandle;  /*  Semaphore handle to destroy */
 
VDHDestroySem(SemHandle);</pre>
 
 
 
 
=== VDHDestroySem Parameter - SemHandle ===
 
'''SemHandle'''(HVDHSEM) Handle of the semaphore to destroy.
 
 
 
 
 
=== VDHDestroySem - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''SemHandle''is invalid or if the semaphore is reset or owned, a system halt occurs.
 
 
 
 
 
=== VDHDestroySem - Parameters ===
 
'''SemHandle'''(HVDHSEM) Handle of the semaphore to destroy.
 
Success If the function is successful, it returns nothing.
 
Failure If ''SemHandle''is invalid or if the semaphore is reset or owned, a system halt occurs.
 
 
 
 
 
=== VDHDestroySem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHDestroySem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDevBeep ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function performs the preempt beep request on behalf of the requesting virtual device driver.
 
<pre class="western">#include mvdm.h
 
ULONG    Frequency;  /*  Frequency of the beep in hertz */
ULONG    Duration;  /*  Duration of the beep in milliseconds */
BOOL    rc;
 
rc = VDHDevBeep(Frequency, Duration);</pre>
 
 
 
 
=== VDHDevBeep - Format ===
 
This function performs the preempt beep request on behalf of the requesting virtual device driver.
 
<pre class="western">#include mvdm.h
 
ULONG    Frequency;  /*  Frequency of the beep in hertz */
ULONG    Duration;  /*  Duration of the beep in milliseconds */
BOOL    rc;
 
rc = VDHDevBeep(Frequency, Duration);</pre>
 
 
 
 
=== VDHDevBeep Parameter - Frequency ===
 
'''Frequency'''(ULONG) Frequency of the beep in hertz.
 
 
 
 
 
=== VDHDevBeep Parameter - Duration ===
 
'''Duration'''(ULONG) Duration of the beep in milliseconds.
 
 
 
 
 
=== VDHDevBeep Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0.
 
 
 
 
 
=== VDHDevBeep - Parameters ===
 
'''Frequency'''(ULONG) Frequency of the beep in hertz.
 
'''Duration'''(ULONG) Duration of the beep in milliseconds.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0.
 
 
 
 
 
=== VDHDevBeep - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHDevBeep - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDevIOCtl ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function allows a virtual device driver to send device-specific commands to a physical device driver through the generic IOCtl interface. The parameters and error return codes are identical to the ones found in the ''DosDevIOCtl''API. Refer to the ''OS/2 Control Program Programming Reference''for a complete description of each ''DosDevIOCtl''API parameter.
 
<pre class="western">#include mvdm.h
 
HFILE    DevHandle;        /*  Device handle returned by VDHOpen or VDHPhysicalDisk */
ULONG    Category;        /*  Category of function performed */
ULONG    Function;        /*  Function within category performed */
PVOID    ParmList;        /*  Pointer to command-specific input parameter area */
ULONG    ParmLengthMax;    /*  Maximum size of input parameter area, in bytes */
PULONG    ParmLengthInOut;  /*  Pointer to length of the parameters passed, in bytes */
PVOID    DataArea;        /*  Pointer to the data area */
ULONG    DataLengthMax;    /*  Maximum size of the parameters passed, in bytes */
PULONG    DataLengthInOut;  /*  Pointer to length of the parameters passed, in bytes */
HFILE    rc;
 
rc = VDHDevIOCtl(DevHandle, Category, Function,
      ParmList, ParmLengthMax, ParmLengthInOut,
      DataArea, DataLengthMax, DataLengthInOut);</pre>
 
 
 
 
=== VDHDevIOCtl - Format ===
 
This function allows a virtual device driver to send device-specific commands to a physical device driver through the generic IOCtl interface. The parameters and error return codes are identical to the ones found in the ''DosDevIOCtl''API. Refer to the ''OS/2 Control Program Programming Reference''for a complete description of each ''DosDevIOCtl''API parameter.
 
<pre class="western">#include mvdm.h
 
HFILE    DevHandle;        /*  Device handle returned by VDHOpen or VDHPhysicalDisk */
ULONG    Category;        /*  Category of function performed */
ULONG    Function;        /*  Function within category performed */
PVOID    ParmList;        /*  Pointer to command-specific input parameter area */
ULONG    ParmLengthMax;    /*  Maximum size of input parameter area, in bytes */
PULONG    ParmLengthInOut;  /*  Pointer to length of the parameters passed, in bytes */
PVOID    DataArea;        /*  Pointer to the data area */
ULONG    DataLengthMax;    /*  Maximum size of the parameters passed, in bytes */
PULONG    DataLengthInOut;  /*  Pointer to length of the parameters passed, in bytes */
HFILE    rc;
 
rc = VDHDevIOCtl(DevHandle, Category, Function,
      ParmList, ParmLengthMax, ParmLengthInOut,
      DataArea, DataLengthMax, DataLengthInOut);</pre>
 
 
 
 
=== VDHDevIOCtl Parameter - DevHandle ===
 
'''DevHandle'''(HFILE) Device handle returned by ''VDHOpen''or ''VDHPhysicalDisk''.
 
 
 
 
 
=== VDHDevIOCtl Parameter - Category ===
 
'''Category'''(ULONG) Category of function performed.
 
 
 
 
 
=== VDHDevIOCtl Parameter - Function ===
 
'''Function'''(ULONG) Function within category performed.
 
 
 
 
 
=== VDHDevIOCtl Parameter - ParmList ===
 
'''ParmList'''(PVOID) Pointer to the command-specific input parameter area.
 
 
 
 
 
=== VDHDevIOCtl Parameter - ParmLengthMax ===
 
'''ParmLengthMax'''(ULONG) Maximum size of the application input parameter area, in bytes. ''ParmLengthInOut''can be longer than this on input, but not on output.
 
 
 
 
 
=== VDHDevIOCtl Parameter - ParmLengthInOut ===
 
'''ParmLengthInOut'''(PULONG) Pointer to the length (in bytes) of the parameters passed by the caller in ''ParmList''.
 
 
 
 
 
=== VDHDevIOCtl Parameter - DataArea ===
 
'''DataArea'''(PVOID) Pointer to the data area.
 
 
 
 
 
=== VDHDevIOCtl Parameter - DataLengthMax ===
 
'''DataLengthMax'''(ULONG) Maximum size of the application data area, in bytes.
 
 
 
 
 
=== VDHDevIOCtl Parameter - DataLengthInOut ===
 
'''DataLengthInOut'''(PULONG) Pointer to the length (in bytes) of the parameters passed by the caller in ''ParmList''. ''ParmLengthInOut''can be longer than this on input, but not on output.
 
 
 
 
 
=== VDHDevIOCtl Return Value - rc ===
 
'''rc'''(HFILE) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. ''VDHGetError''can return the following errors:
 
ERROR_INVALID_HANDLE <br />ERROR_INVALID_FUNCTION <br />ERROR_INVALID_CATEGORY <br />ERROR_INVALID_DRIVE <br />ERROR_INVALID_PARAMETER.
 
If the function is called when not at DOS session-task time, a system halt occurs.
 
 
 
 
 
=== VDHDevIOCtl - Parameters ===
 
'''DevHandle'''(HFILE) Device handle returned by ''VDHOpen''or ''VDHPhysicalDisk''.
 
'''Category'''(ULONG) Category of function performed.
 
'''Function'''(ULONG) Function within category performed.
 
'''ParmList'''(PVOID) Pointer to the command-specific input parameter area.
 
'''ParmLengthMax'''(ULONG) Maximum size of the application input parameter area, in bytes. ''ParmLengthInOut''can be longer than this on input, but not on output.
 
'''ParmLengthInOut'''(PULONG) Pointer to the length (in bytes) of the parameters passed by the caller in ''ParmList''.
 
'''DataArea'''(PVOID) Pointer to the data area.
 
'''DataLengthMax'''(ULONG) Maximum size of the application data area, in bytes.
 
'''DataLengthInOut'''(PULONG) Pointer to the length (in bytes) of the parameters passed by the caller in ''ParmList''. ''ParmLengthInOut''can be longer than this on input, but not on output.
 
'''rc'''(HFILE) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. ''VDHGetError''can return the following errors:
 
ERROR_INVALID_HANDLE <br />ERROR_INVALID_FUNCTION <br />ERROR_INVALID_CATEGORY <br />ERROR_INVALID_DRIVE <br />ERROR_INVALID_PARAMETER.
 
If the function is called when not at DOS session-task time, a system halt occurs.
 
 
 
 
 
=== VDHDevIOCtl - Purpose ===
 
Context Issues: This function can be called only in the DOS session task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Addresses (pointers) inside device-specific Data or Parameter Packets are not translated.
 
 
 
 
 
=== VDHDevIOCtl - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDisarmTimerHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function cancels a timer that was installed by ''VDHArmTimerHook''before the handler was called.
 
<pre class="western">#include mvdm.h
 
HHOOK    TimerHook;  /*  Handle to the timer hook to disarm */
BOOL    rc;
 
rc = VDHDisarmTimerHook(TimerHook);</pre>
 
 
 
 
=== VDHDisarmTimerHook - Format ===
 
This function cancels a timer that was installed by ''VDHArmTimerHook''before the handler was called.
 
<pre class="western">#include mvdm.h
 
HHOOK    TimerHook;  /*  Handle to the timer hook to disarm */
BOOL    rc;
 
rc = VDHDisarmTimerHook(TimerHook);</pre>
 
 
 
 
=== VDHDisarmTimerHook Parameter - TimerHook ===
 
'''TimerHook'''(HHOOK) Handle to the timer hook to disarm.
 
 
 
 
 
=== VDHDisarmTimerHook Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''TimerHook''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHDisarmTimerHook - Parameters ===
 
'''TimerHook'''(HHOOK) Handle to the timer hook to disarm.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''TimerHook''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHDisarmTimerHook - Purpose ===
 
Context Issues: This function can be called in the initialization, task, or interrupt context.
 
DOS Session Terminations: Any timer hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager at DOS session termination.
 
 
 
 
 
=== VDHDisarmTimerHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHEndUseVPMStack ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function must be called once with every call made to ''VDHBeginUseVPMStack''. It switches back to the original DOS session protected -mode stack when the use count goes to zero.
 
<pre class="western">#include mvdm.h
 
VOID    ;
 
VDHEndUseVPMStack();</pre>
 
 
 
 
=== VDHEndUseVPMStack - Format ===
 
This function must be called once with every call made to ''VDHBeginUseVPMStack''. It switches back to the original DOS session protected -mode stack when the use count goes to zero.
 
<pre class="western">#include mvdm.h
 
VOID    ;
 
VDHEndUseVPMStack();</pre>
 
 
 
 
=== VDHEndUseVPMStack Parameter - ===
 
None.
 
 
 
 
 
=== VDHEndUseVPMStack - Return Value ===
 
None.
 
 
 
 
 
=== VDHEndUseVPMStack - Parameters ===
 
None.
 
None.
 
 
 
 
 
=== VDHEndUseVPMStack - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: There must be a DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHEndUseVPMStack - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHEnumerateVDMs ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used to run a worker function for each DOS session in the system. The worker function can stop the enumeration by returning 0.
 
<pre class="western">#include mvdm.h
 
PENUMHOOK    WorkerFcn;  /*  Worker function */
ULONG        FcnData;    /*  Function-specific data to be passed each call */
BOOL        rc;
 
rc = VDHEnumerateVDMs(WorkerFcn, FcnData);</pre>
 
 
 
 
=== VDHEnumerateVDMs - Format ===
 
This function is used to run a worker function for each DOS session in the system. The worker function can stop the enumeration by returning 0.
 
<pre class="western">#include mvdm.h
 
PENUMHOOK    WorkerFcn;  /*  Worker function */
ULONG        FcnData;    /*  Function-specific data to be passed each call */
BOOL        rc;
 
rc = VDHEnumerateVDMs(WorkerFcn, FcnData);</pre>
 
 
 
 
=== VDHEnumerateVDMs Parameter - WorkerFcn ===
 
'''WorkerFcn'''(PENUMHOOK) Worker function, the routine that does the work.
 
The worker function uses the following interface:
 
<pre class="western"> BOOL HOOKENTRY fnworker (hVDM, ulData)
      ENTRY        hVDM  - Handle to DOS session
                    ulData - Function-specific data
      EXIT-SUCCESS  Return a non-zero value, enumeration continues
      EXIT-FAILURE  Return 0, stop enumeration</pre>
 
 
 
 
 
 
=== VDHEnumerateVDMs Parameter - FcnData ===
 
'''FcnData'''(ULONG) Function-specific data to be passed each call.
 
 
 
 
 
=== VDHEnumerateVDMs Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 indicating that a worker function stopped the enumeration.
 
 
 
 
 
=== VDHEnumerateVDMs - Parameters ===
 
'''WorkerFcn'''(PENUMHOOK) Worker function, the routine that does the work.
 
The worker function uses the following interface:
 
<pre class="western"> BOOL HOOKENTRY fnworker (hVDM, ulData)
      ENTRY        hVDM  - Handle to DOS session
                    ulData - Function-specific data
      EXIT-SUCCESS  Return a non-zero value, enumeration continues
      EXIT-FAILURE  Return 0, stop enumeration</pre>
 
 
'''FcnData'''(ULONG) Function-specific data to be passed each call.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 indicating that a worker function stopped the enumeration.
 
 
 
 
 
=== VDHEnumerateVDMs - Purpose ===
 
Context Issues: This function can be called in the task and interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHEnumerateVDMs - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHExchangeMem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function exchanges the contents of two regions of linear address space . Overlapping regions are not supported.
 
<pre class="western">#include mvdm.h
 
PVOID    Source;      /*  Source data address */
PVOID    Destination;  /*  Destination address */
ULONG    NumBytes;    /*  Number of bytes to be exchanged */
BOOL    rc;
 
rc = VDHExchangeMem(Source, Destination, NumBytes);</pre>
 
 
 
 
=== VDHExchangeMem - Format ===
 
This function exchanges the contents of two regions of linear address space . Overlapping regions are not supported.
 
<pre class="western">#include mvdm.h
 
PVOID    Source;      /*  Source data address */
PVOID    Destination;  /*  Destination address */
ULONG    NumBytes;    /*  Number of bytes to be exchanged */
BOOL    rc;
 
rc = VDHExchangeMem(Source, Destination, NumBytes);</pre>
 
 
 
 
=== VDHExchangeMem Parameter - Source ===
 
'''Source'''(PVOID) Address of the source data.
 
 
 
 
 
=== VDHExchangeMem Parameter - Destination ===
 
'''Destination'''(PVOID) Address of the target region.
 
 
 
 
 
=== VDHExchangeMem Parameter - NumBytes ===
 
'''NumBytes'''(ULONG) Number of bytes to exchange.
 
 
 
 
 
=== VDHExchangeMem Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHExchangeMem - Parameters ===
 
'''Source'''(PVOID) Address of the source data.
 
'''Destination'''(PVOID) Address of the target region.
 
'''NumBytes'''(ULONG) Number of bytes to exchange.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHExchangeMem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This function fails if the two memory regions to be exchanged overlap. Protection faults are handled as if a user application had performed the access. Therefore, writing to read-only pages or invalid page -table entries causes a virtual device driver page fault handler to gain control or causes the default behavior (that is, DOS session termination). This function also yields the CPU, if it is necessary to ensure that the thread dispatch latency limit is not exceeded.
 
 
 
 
 
=== VDHExchangeMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFindFreePages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function starts at a specified linear address and searches linear memory (up to a specified limit) for the largest free linear memory block. The address and size of the largest region found are returned.
 
<pre class="western">#include mvdm.h
 
PVOID    StartAddress;  /*  Starting address */
PULONG    Pages;        /*  Size of the range (in pages) */
PVOID    rc;
 
rc = VDHFindFreePages(StartAddress, Pages);</pre>
 
 
 
 
=== VDHFindFreePages - Format ===
 
This function starts at a specified linear address and searches linear memory (up to a specified limit) for the largest free linear memory block. The address and size of the largest region found are returned.
 
<pre class="western">#include mvdm.h
 
PVOID    StartAddress;  /*  Starting address */
PULONG    Pages;        /*  Size of the range (in pages) */
PVOID    rc;
 
rc = VDHFindFreePages(StartAddress, Pages);</pre>
 
 
 
 
=== VDHFindFreePages Parameter - StartAddress ===
 
'''StartAddress'''(PVOID) Starting address of the linear memory range to be searched. Must be page-aligned and between 0 and 110000H (1MB+64KB).
 
 
 
 
 
=== VDHFindFreePages Parameter - Pages ===
 
'''Pages'''(PULONG) On input: The size of the linear memory range to search, in pages.
 
On output: The size of the region found, in pages.
 
 
 
 
 
=== VDHFindFreePages Return Value - rc ===
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the address of the region found and sets ''Pages''to the size of the region found (in pages).
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHFindFreePages - Parameters ===
 
'''StartAddress'''(PVOID) Starting address of the linear memory range to be searched. Must be page-aligned and between 0 and 110000H (1MB+64KB).
 
'''Pages'''(PULONG) On input: The size of the linear memory range to search, in pages.
 
On output: The size of the region found, in pages.
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the address of the region found and sets ''Pages''to the size of the region found (in pages).
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHFindFreePages - Purpose ===
 
Context Issues: This function can be called in the initialization context where it searches only the global linear map. This function can also be called in DOS session-task context (DOS session creation only), where it searches only the DOS session's private linear map.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHFindFreePages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFreeBlock ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function releases a memory block previously allocated by ''VDHAllocBlock'' . The memory block is returned to the user's memory block pool for reuse.
 
<pre class="western">#include mvdm.h
 
HBLOCK    PoolHandle;  /*  Handle to a memory block pool */
PVOID    BlockToFree;  /*  Address of the memory block to free */
 
VDHFreeBlock(PoolHandle, BlockToFree);</pre>
 
 
 
 
=== VDHFreeBlock - Format ===
 
This function releases a memory block previously allocated by ''VDHAllocBlock'' . The memory block is returned to the user's memory block pool for reuse.
 
<pre class="western">#include mvdm.h
 
HBLOCK    PoolHandle;  /*  Handle to a memory block pool */
PVOID    BlockToFree;  /*  Address of the memory block to free */
 
VDHFreeBlock(PoolHandle, BlockToFree);</pre>
 
 
 
 
=== VDHFreeBlock Parameter - PoolHandle ===
 
'''PoolHandle'''(HBLOCK) Handle (from ''VDHCreateBlockPool'') to the pool of memory blocks that contains the memory block to free.
 
 
 
 
 
=== VDHFreeBlock Parameter - BlockToFree ===
 
'''BlockToFree'''(PVOID) Address of the memory block to free.
 
 
 
 
 
=== VDHFreeBlock - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''BlockPool''is not a valid handle to a memory block pool, or if ''BlockToFree''is not a block allocated from the ''BlockPool''memory block pool, a system halt occurs.
 
 
 
 
 
=== VDHFreeBlock - Parameters ===
 
'''PoolHandle'''(HBLOCK) Handle (from ''VDHCreateBlockPool'') to the pool of memory blocks that contains the memory block to free.
 
'''BlockToFree'''(PVOID) Address of the memory block to free.
 
Success If the function is successful, it returns nothing.
 
Failure If ''BlockPool''is not a valid handle to a memory block pool, or if ''BlockToFree''is not a block allocated from the ''BlockPool''memory block pool, a system halt occurs.
 
 
 
 
 
=== VDHFreeBlock - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: The only way to reclaim memory for freed blocks is to call ''VDHDestroyBlockPool''.
 
 
 
 
 
=== VDHFreeBlock - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFreeDMABuffer ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function frees a DMA buffer previously allocated by ''VDHAllocDMABuffer''.
 
<pre class="western">#include mvdm.h
 
PVOID    LinearAddress;  /*  Starting linear address of the DMA buffer */
 
VDHFreeDMABuffer(LinearAddress);</pre>
 
 
 
 
=== VDHFreeDMABuffer - Format ===
 
This function frees a DMA buffer previously allocated by ''VDHAllocDMABuffer''.
 
<pre class="western">#include mvdm.h
 
PVOID    LinearAddress;  /*  Starting linear address of the DMA buffer */
 
VDHFreeDMABuffer(LinearAddress);</pre>
 
 
 
 
=== VDHFreeDMABuffer Parameter - LinearAddress ===
 
'''LinearAddress'''(PVOID) Starting linear address of the DMA buffer.
 
 
 
 
 
=== VDHFreeDMABuffer - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''LinearAddress''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHFreeDMABuffer - Parameters ===
 
'''LinearAddress'''(PVOID) Starting linear address of the DMA buffer.
 
Success If the function is successful, it returns nothing.
 
Failure If ''LinearAddress''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHFreeDMABuffer - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHFreeDMABuffer - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFreeHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function disarms and frees a hook.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle from VDHAllocHook */
 
VDHFreeHook(HookHandle);</pre>
 
 
 
 
=== VDHFreeHook - Format ===
 
This function disarms and frees a hook.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle from VDHAllocHook */
 
VDHFreeHook(HookHandle);</pre>
 
 
 
 
=== VDHFreeHook Parameter - HookHandle ===
 
'''HookHandle'''(HHOOK) Hook handle (from ''VDHAllocHook'') for the hook to free.
 
 
 
 
 
=== VDHFreeHook - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''HookHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHFreeHook - Parameters ===
 
'''HookHandle'''(HHOOK) Hook handle (from ''VDHAllocHook'') for the hook to free.
 
Success If the function is successful, it returns nothing.
 
Failure If ''HookHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHFreeHook - Purpose ===
 
Context Issues: This function can be called in the initialization or DOS session-task context.
 
DOS Session Terminations: Any context hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager.
 
 
 
 
 
=== VDHFreeHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFreeMem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function frees memory that was previously allocated by ''VDHAllocMem''.
 
<pre class="western">#include mvdm.h
 
PVOID    MemAddress;  /*  Address of the memory block to free */
 
VDHFreeMem(MemAddress);</pre>
 
 
 
 
=== VDHFreeMem - Format ===
 
This function frees memory that was previously allocated by ''VDHAllocMem''.
 
<pre class="western">#include mvdm.h
 
PVOID    MemAddress;  /*  Address of the memory block to free */
 
VDHFreeMem(MemAddress);</pre>
 
 
 
 
=== VDHFreeMem Parameter - MemAddress ===
 
'''MemAddress'''(PVOID) Address of the memory block to be freed. Pointer is originally obtained from ''VDHAllocMem''.
 
 
 
 
 
=== VDHFreeMem - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''MemAddress''is not an address pointer allocated by ''VDHAllocMem'', a system halt occurs.
 
 
 
 
 
=== VDHFreeMem - Parameters ===
 
'''MemAddress'''(PVOID) Address of the memory block to be freed. Pointer is originally obtained from ''VDHAllocMem''.
 
Success If the function is successful, it returns nothing.
 
Failure If ''MemAddress''is not an address pointer allocated by ''VDHAllocMem'', a system halt occurs.
 
 
 
 
 
=== VDHFreeMem - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHFreeMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFreePages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function frees a memory object. All the memory associated with the memory object is released.
 
<pre class="western">#include mvdm.h
 
PVOID    ObjectAddress;  /*  Address of the memory object to free */
 
VDHFreePages(ObjectAddress);</pre>
 
 
 
 
=== VDHFreePages - Format ===
 
This function frees a memory object. All the memory associated with the memory object is released.
 
<pre class="western">#include mvdm.h
 
PVOID    ObjectAddress;  /*  Address of the memory object to free */
 
VDHFreePages(ObjectAddress);</pre>
 
 
 
 
=== VDHFreePages Parameter - ObjectAddress ===
 
'''ObjectAddress'''(PVOID) Address of the memory object to free.
 
 
 
 
 
=== VDHFreePages - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''ObjectAddress''was not allocated by ''VDHAllocPages''or ''VDHReallocPages'', a system halt occurs.
 
 
 
 
 
=== VDHFreePages - Parameters ===
 
'''ObjectAddress'''(PVOID) Address of the memory object to free.
 
Success If the function is successful, it returns nothing.
 
Failure If ''ObjectAddress''was not allocated by ''VDHAllocPages''or ''VDHReallocPages'', a system halt occurs.
 
 
 
 
 
=== VDHFreePages - Purpose ===
 
Context Issues: This function can be called in the initialization or task context. At initialization time, only global memory can be freed.
 
DOS Session Terminations: Any allocations made in the terminating DOS session's private area, or on behalf of the terminating DOS session, must be released by using ''VDHFreePages''.
 
Notes: This function succeeds only if the linear range specified was allocated by a previous call to ''VDHAllocPages''or ''VDHReallocPages''. Freeing a memory region that was not allocated causes an internal error (a probable system halt).
 
If the region, starting at ''ObjectAddress'', has been broken into two or more regions by calls to ''VDHMapPages'', then ''VDHFreePages''is not used.
 
 
 
 
 
=== VDHFreePages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFreezeVDM ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function freezes a DOS session, which prevents it from executing. The specified DOS session is not allowed to execute any V86-mode code until ''VDHThawVDM''is called. This freeze occurs when the specified DOS session leaves kernel mode. The DOS session does not execute any V86-mode code from the time ''VDHFreezeVDM''is called until the matching ''VDHThawVDM''is called.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Handle to the DOS session to freeze */
BOOL    rc;
 
rc = VDHFreezeVDM(VDMHandle);</pre>
 
 
 
 
=== VDHFreezeVDM - Format ===
 
This function freezes a DOS session, which prevents it from executing. The specified DOS session is not allowed to execute any V86-mode code until ''VDHThawVDM''is called. This freeze occurs when the specified DOS session leaves kernel mode. The DOS session does not execute any V86-mode code from the time ''VDHFreezeVDM''is called until the matching ''VDHThawVDM''is called.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Handle to the DOS session to freeze */
BOOL    rc;
 
rc = VDHFreezeVDM(VDMHandle);</pre>
 
 
 
 
=== VDHFreezeVDM Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session to freeze.
 
 
 
 
 
=== VDHFreezeVDM Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''VDMHandle''is not a valid DOS session handle, a system halt occurs.
 
 
 
 
 
=== VDHFreezeVDM - Parameters ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session to freeze.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''VDMHandle''is not a valid DOS session handle, a system halt occurs.
 
 
 
 
 
=== VDHFreezeVDM - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: The DOS Session Manager thaws a frozen DOS session prior to calling any VDM_TERMINATE user hooks.
 
Notes: Each DOS session has a freeze count. This count starts at zero when the DOS session is created. Each ''VDHFreezeVDM''call adds one to this count. Each ''VDHThawVDM''call subtracts one from this count. The DOS session is frozen when the freeze count is 1 (one) or greater. The DOS session is thawed when the freeze count is 0 (zero). This allows multiple virtual device drivers to perform freeze and thaw operations without inadvertently causing the DOS session to run. If this count exceeds MAX_FREEZE_COUNT, ''VDHFreezeVDM''returns VDHERR_FROZEN_LIMIT.
 
 
 
 
 
=== VDHFreezeVDM - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetCodePageFont ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns the address of the code page font information, if code page support is active and a font is available for the given character cell dimensions.
 
<pre class="western">#include mvdm.h
 
ULONG    CellWidth;    /*  Width of character cells, in pels */
ULONG    CellHeight;  /*  Height of character cells, in pels */
PPVOID    FontAddress;  /*  Address where font table addresses will be copied */
ULONG    rc;
 
rc = VDHGetCodePageFont(CellWidth, CellHeight,
      FontAddress);</pre>
 
 
 
 
=== VDHGetCodePageFont - Format ===
 
This function returns the address of the code page font information, if code page support is active and a font is available for the given character cell dimensions.
 
<pre class="western">#include mvdm.h
 
ULONG    CellWidth;    /*  Width of character cells, in pels */
ULONG    CellHeight;  /*  Height of character cells, in pels */
PPVOID    FontAddress;  /*  Address where font table addresses will be copied */
ULONG    rc;
 
rc = VDHGetCodePageFont(CellWidth, CellHeight,
      FontAddress);</pre>
 
 
 
 
=== VDHGetCodePageFont Parameter - CellWidth ===
 
'''CellWidth'''(ULONG) Width of character cells, measured in pels.
 
 
 
 
 
=== VDHGetCodePageFont Parameter - CellHeight ===
 
'''CellHeight'''(ULONG) Height of character cells, measured in pels.
 
 
 
 
 
=== VDHGetCodePageFont Parameter - FontAddress ===
 
'''FontAddress'''(PPVOID) Address to which font table addresses will be copied.
 
 
 
 
 
=== VDHGetCodePageFont Return Value - rc ===
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the size of the font table in bytes.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHGetCodePageFont - Parameters ===
 
'''CellWidth'''(ULONG) Width of character cells, measured in pels.
 
'''CellHeight'''(ULONG) Height of character cells, measured in pels.
 
'''FontAddress'''(PPVOID) Address to which font table addresses will be copied.
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the size of the font table in bytes.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHGetCodePageFont - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: If this function was called on behalf of the terminating DOS session, ''VDHReleaseCodePageFont''must be called to release the fonts.
 
Notes: System memory can be allocated to hold the font, especially if it is a merged font (that is, merged from two separate font tables). When the virtual device driver is finished with the font, it must call ''VDHReleaseCodePageFont''.
 
 
 
 
 
=== VDHGetCodePageFont - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetDirtyPageInfo ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns a bit vector for the dirty pages of a specified DOS session for a specified range of pages. The dirty bits for the range are reset.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;        /*  Handle to the DOS session that owns the object */
PVOID    StartingAddress;  /*  Address to start the scan */
ULONG    PageRange;        /*  Range of pages to scan */
ULONG    rc;
 
rc = VDHGetDirtyPageInfo(VDMHandle, StartingAddress,
      PageRange);</pre>
 
 
 
 
=== VDHGetDirtyPageInfo - Format ===
 
This function returns a bit vector for the dirty pages of a specified DOS session for a specified range of pages. The dirty bits for the range are reset.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;        /*  Handle to the DOS session that owns the object */
PVOID    StartingAddress;  /*  Address to start the scan */
ULONG    PageRange;        /*  Range of pages to scan */
ULONG    rc;
 
rc = VDHGetDirtyPageInfo(VDMHandle, StartingAddress,
      PageRange);</pre>
 
 
 
 
=== VDHGetDirtyPageInfo Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session that owns the object. A 0 (zero) value indicates the current DOS session.
 
 
 
 
 
=== VDHGetDirtyPageInfo Parameter - StartingAddress ===
 
'''StartingAddress'''(PVOID) Starting address of the range of pages to scan.
 
 
 
 
 
=== VDHGetDirtyPageInfo Parameter - PageRange ===
 
'''PageRange'''(ULONG) Range (number of pages) to scan. Maximum allowed is 32.
 
 
 
 
 
=== VDHGetDirtyPageInfo Return Value - rc ===
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the bit vector. The low- order bit (that is, bit 0, the rightmost bit) is the dirty bit for the first page scanned. Bit 1 (from the right) is the dirty bit for the next page, and so forth for all the pages scanned.
 
Failure If any of the input parameters are invalid, a system halt occurs.
 
 
 
 
 
=== VDHGetDirtyPageInfo - Parameters ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session that owns the object. A 0 (zero) value indicates the current DOS session.
 
'''StartingAddress'''(PVOID) Starting address of the range of pages to scan.
 
'''PageRange'''(ULONG) Range (number of pages) to scan. Maximum allowed is 32.
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the bit vector. The low- order bit (that is, bit 0, the rightmost bit) is the dirty bit for the first page scanned. Bit 1 (from the right) is the dirty bit for the next page, and so forth for all the pages scanned.
 
Failure If any of the input parameters are invalid, a system halt occurs.
 
 
 
 
 
=== VDHGetDirtyPageInfo - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: The virtual dirty bits remain set until cleared by this function, regardless of the swapping activity that has occurred. The actual dirty bits in the page tables are reset whenever a page is swapped to the swap device and brought back into memory. This function is valid only for linear addresses up to 110000H (1MB+64KB) in a DOS session.
 
 
 
 
 
=== VDHGetDirtyPageInfo - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetError ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns the error code from the last virtual DevHlp service called.
 
<pre class="western">#include mvdm.h
 
VOID    ;
ULONG    rc;
 
rc = VDHGetError();</pre>
 
 
 
 
=== VDHGetError - Format ===
 
This function returns the error code from the last virtual DevHlp service called.
 
<pre class="western">#include mvdm.h
 
VOID    ;
ULONG    rc;
 
rc = VDHGetError();</pre>
 
 
 
 
=== VDHGetError Parameter - ===
 
None.
 
 
 
 
 
=== VDHGetError Return Value - rc ===
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the error code.
 
Failure If the function fails, it returns 0, indicating that the last virtual DevHlp call did not have an error.
 
 
 
 
 
=== VDHGetError - Parameters ===
 
None.
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the error code.
 
Failure If the function fails, it returns 0, indicating that the last virtual DevHlp call did not have an error.
 
 
 
 
 
=== VDHGetError - Purpose ===
 
Context Issues: This function can be called in any context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: The return value is guaranteed to be valid as long as the virtual device driver does not block or yield between the virtual DevHlp service that failed and the call to ''VDHGetError''. ''VDHGetError''and ''VDHSetError''work at hardware interrupt time. Each level of interrupt nesting (where task time is Level 0) has a separate error code variable.
 
 
 
 
 
=== VDHGetError - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetFlags ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function gets the DOS session's EFlags Register.
 
<pre class="western">#include mvdm.h
 
ULONG    ulFlagsAddr;  /*  DOS session flag address. */
 
VDHGetFlags(ulFlagsAddr);</pre>
 
 
 
 
=== VDHGetFlags - Format ===
 
This function gets the DOS session's EFlags Register.
 
<pre class="western">#include mvdm.h
 
ULONG    ulFlagsAddr;  /*  DOS session flag address. */
 
VDHGetFlags(ulFlagsAddr);</pre>
 
 
 
 
=== VDHGetFlags Parameter - ulFlagsAddr ===
 
'''ulFlagsAddr'''(ULONG) Address of the ULONG in which the EFLAGs value is to be returned.
 
 
 
 
 
=== VDHGetFlags - Return Value ===
 
None.
 
 
 
 
 
=== VDHGetFlags - Parameters ===
 
'''ulFlagsAddr'''(ULONG) Address of the ULONG in which the EFLAGs value is to be returned.
 
None.
 
 
 
 
 
=== VDHGetFlags - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Virtual device drivers must use this interface instead of the client register frame pointer to change the DOS session's flags. Changes to the interrupt flag and the I/O Privilege Level (IOPL) field must be under the control of 8086 emulation so that ''VDHArmSTIHook''works correctly.
 
Getting the Interrupt Flag (IF) must be under 8086 emulation control due to virtual mode extensions and DPMI.
 
 
 
 
 
=== VDHGetFlags - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetSelBase ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns the base address for a Local Descriptor Table (LDT) selector.
 
<pre class="western">#include mvdm.h
 
SEL      Selector;      /*  LDT selector */
PULONG    pBasePointer;  /*  Pointer for returned address */
BOOL      rc;
 
rc = VDHGetSelBase(Selector, pBasePointer);</pre>
 
 
 
 
=== VDHGetSelBase - Format ===
 
This function returns the base address for a Local Descriptor Table (LDT) selector.
 
<pre class="western">#include mvdm.h
 
SEL      Selector;      /*  LDT selector */
PULONG    pBasePointer;  /*  Pointer for returned address */
BOOL      rc;
 
rc = VDHGetSelBase(Selector, pBasePointer);</pre>
 
 
 
 
=== VDHGetSelBase Parameter - Selector ===
 
'''Selector'''(SEL) LDT Selector.
 
 
 
 
 
=== VDHGetSelBase Parameter - pBasePointer ===
 
'''pBasePointer'''(PULONG) Pointer for returned address.
 
 
 
 
 
=== VDHGetSelBase Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value. The base address is returned in the variable pointed to by ''pBasePointer''.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHGetSelBase - Parameters ===
 
'''Selector'''(SEL) LDT Selector.
 
'''pBasePointer'''(PULONG) Pointer for returned address.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value. The base address is returned in the variable pointed to by ''pBasePointer''.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHGetSelBase - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Error checking is performed only to ensure that the selector is allocated.
 
 
 
 
 
=== VDHGetSelBase - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetVPMExcept ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function gets the current value from the protected-mode exception table.
 
<pre class="western">#include mvdm.h
 
ULONG    Vector;                  /*  Exception vector number */
PFPFN    pHandlerAddressPointer;  /*  Pointer to put handler address */
PBYTE    pFlag;                  /*  Pointer to a flag variable */
BOOL    rc;
 
rc = VDHGetVPMExcept(Vector, pHandlerAddressPointer,
      pFlag);</pre>
 
 
 
 
=== VDHGetVPMExcept - Format ===
 
This function gets the current value from the protected-mode exception table.
 
<pre class="western">#include mvdm.h
 
ULONG    Vector;                  /*  Exception vector number */
PFPFN    pHandlerAddressPointer;  /*  Pointer to put handler address */
PBYTE    pFlag;                  /*  Pointer to a flag variable */
BOOL    rc;
 
rc = VDHGetVPMExcept(Vector, pHandlerAddressPointer,
      pFlag);</pre>
 
 
 
 
=== VDHGetVPMExcept Parameter - Vector ===
 
'''Vector'''(ULONG) Exception vector number (''0''-1FH).
 
 
 
 
 
=== VDHGetVPMExcept Parameter - pHandlerAddressPointer ===
 
'''pHandlerAddressPointer'''(PFPFN) Pointer to put handler address.
 
 
 
 
 
=== VDHGetVPMExcept Parameter - pFlag ===
 
'''pFlag'''(PBYTE) Pointer to a flag variable for returning the flag value. Possible values are:
 
VPMXCPT32 A 32-bit handler was registered. <br />VPMXCPT_REFLECT The exception is reflected back to a V86-mode handler.
 
 
 
 
 
=== VDHGetVPMExcept Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0.
 
 
 
 
 
=== VDHGetVPMExcept - Parameters ===
 
'''Vector'''(ULONG) Exception vector number (''0''-1FH).
 
'''pHandlerAddressPointer'''(PFPFN) Pointer to put handler address.
 
'''pFlag'''(PBYTE) Pointer to a flag variable for returning the flag value. Possible values are:
 
VPMXCPT32 A 32-bit handler was registered. <br />VPMXCPT_REFLECT The exception is reflected back to a V86-mode handler.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0.
 
 
 
 
 
=== VDHGetVPMExcept - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: There must be a DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHGetVPMExcept - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetVPMIntVector ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function gets the application Ring 3 protected-mode interrupt handler. This service is used only for DOS Protected-Mode Interface (DPMI) support.
 
<pre class="western">#include mvdm.h
 
ULONG    Vector;                /*  Interrupt vector number */
PFPFN    HandlerAddressPointer;  /*  Pointer for return of handler address */
BOOL    rc;
 
rc = VDHGetVPMIntVector(Vector, HandlerAddressPointer);</pre>
 
 
 
 
=== VDHGetVPMIntVector - Format ===
 
This function gets the application Ring 3 protected-mode interrupt handler. This service is used only for DOS Protected-Mode Interface (DPMI) support.
 
<pre class="western">#include mvdm.h
 
ULONG    Vector;                /*  Interrupt vector number */
PFPFN    HandlerAddressPointer;  /*  Pointer for return of handler address */
BOOL    rc;
 
rc = VDHGetVPMIntVector(Vector, HandlerAddressPointer);</pre>
 
 
 
 
=== VDHGetVPMIntVector Parameter - Vector ===
 
'''Vector'''(ULONG) Interrupt vector number.
 
 
 
 
 
=== VDHGetVPMIntVector Parameter - HandlerAddressPointer ===
 
'''HandlerAddressPointer'''(PFPFN) Pointer for return of the handler address.
 
 
 
 
 
=== VDHGetVPMIntVector Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0.
 
 
 
 
 
=== VDHGetVPMIntVector - Parameters ===
 
'''Vector'''(ULONG) Interrupt vector number.
 
'''HandlerAddressPointer'''(PFPFN) Pointer for return of the handler address.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0.
 
 
 
 
 
=== VDHGetVPMIntVector - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
'''Note:'''There must be a DPMI client in the DOS session before calling this function.
 
 
 
 
 
=== VDHGetVPMIntVector - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHHaltSystem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function causes a system halt.
 
<pre class="western">#include mvdm.h
 
VOID    ;
 
VDHHaltSystem();</pre>
 
 
 
 
=== VDHHaltSystem - Format ===
 
This function causes a system halt.
 
<pre class="western">#include mvdm.h
 
VOID    ;
 
VDHHaltSystem();</pre>
 
 
 
 
=== VDHHaltSystem Parameter - ===
 
None.
 
 
 
 
 
=== VDHHaltSystem - Return Value ===
 
None.
 
 
 
 
 
=== VDHHaltSystem - Parameters ===
 
None.
 
None.
 
 
 
 
 
=== VDHHaltSystem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Calling ''VDHHaltSystem''is an extremely drastic action. Calling ''VDHPopup''and ''VDHKillVDM''is the preferred method for handling a problem. ''VDHHaltSystem''is used only if the virtual device driver is certain that the entire multiple DOS session environment is inoperable. In general, this function is used only by a base virtual device driver (for example, the virtual video device driver or virtual keyboard device driver), whose absence would render the multiple DOS session environment unusable. ''VDHPopup''is called prior to ''VDHHaltSystem''to tell the user what has happened.
 
 
 
 
 
=== VDHHaltSystem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHHandleFromPID ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns the DOS session handle for a given Process ID.
 
<pre class="western">#include mvdm.h
 
PID    ProcessID;  /*  A DOS session process ID */
HVDM    rc;
 
rc = VDHHandleFromPID(ProcessID);</pre>
 
 
 
 
=== VDHHandleFromPID - Format ===
 
This function returns the DOS session handle for a given Process ID.
 
<pre class="western">#include mvdm.h
 
PID    ProcessID;  /*  A DOS session process ID */
HVDM    rc;
 
rc = VDHHandleFromPID(ProcessID);</pre>
 
 
 
 
=== VDHHandleFromPID Parameter - ProcessID ===
 
'''ProcessID'''(PID) A DOS session Process ID.
 
 
 
 
 
=== VDHHandleFromPID Return Value - rc ===
 
'''rc'''(HVDM) - returns
 
Success If the function is successful, it returns the DOS session handle for the Process ID.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHHandleFromPID - Parameters ===
 
'''ProcessID'''(PID) A DOS session Process ID.
 
'''rc'''(HVDM) - returns
 
Success If the function is successful, it returns the DOS session handle for the Process ID.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHHandleFromPID - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHHandleFromPID - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHHandleFromSGID ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function determines the DOS session handle given the Screen Group ID.
 
<pre class="western">#include mvdm.h
 
SGID    ScreenGroupID;  /*  Screen Group ID */
HVDM    rc;
 
rc = VDHHandleFromSGID(ScreenGroupID);</pre>
 
 
 
 
=== VDHHandleFromSGID - Format ===
 
This function determines the DOS session handle given the Screen Group ID.
 
<pre class="western">#include mvdm.h
 
SGID    ScreenGroupID;  /*  Screen Group ID */
HVDM    rc;
 
rc = VDHHandleFromSGID(ScreenGroupID);</pre>
 
 
 
 
=== VDHHandleFromSGID Parameter - ScreenGroupID ===
 
'''ScreenGroupID'''(SGID) Screen Group ID.
 
 
 
 
 
=== VDHHandleFromSGID Return Value - rc ===
 
'''rc'''(HVDM) - returns
 
Success If the function is successful, it returns a handle to the DOS session that was given the Screen Group ID.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHHandleFromSGID - Parameters ===
 
'''ScreenGroupID'''(SGID) Screen Group ID.
 
'''rc'''(HVDM) - returns
 
Success If the function is successful, it returns a handle to the DOS session that was given the Screen Group ID.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHHandleFromSGID - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHHandleFromSGID - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHInstallFaultHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function sets a page fault handler for a region of linear address space. The page fault handler receives control when a DOS session touches a page in a reserved region that was invalidated by VDHMapPages. The handler does not get control if the page was indicated &quot;not present&quot; by the Page Manager.
 
<pre class="western">#include mvdm.h
 
HVDM          VDMHandle;              /*  DOS session handle; 0 = current DOS session */
PVOID        StartingAddress;        /*  Starting linear address */
ULONG        Pages;                  /*  Number of pages */
PFAULTHOOK    PageFaultHandlerFcnPtr;  /*  Page fault handler function */
BOOL          OptionFlag;              /*  Options bit flag */
BOOL          rc;
 
rc = VDHInstallFaultHook(VDMHandle, StartingAddress,
      Pages, PageFaultHandlerFcnPtr, OptionFlag);</pre>
 
 
 
 
=== VDHInstallFaultHook - Format ===
 
This function sets a page fault handler for a region of linear address space. The page fault handler receives control when a DOS session touches a page in a reserved region that was invalidated by VDHMapPages. The handler does not get control if the page was indicated &quot;not present&quot; by the Page Manager.
 
<pre class="western">#include mvdm.h
 
HVDM          VDMHandle;              /*  DOS session handle; 0 = current DOS session */
PVOID        StartingAddress;        /*  Starting linear address */
ULONG        Pages;                  /*  Number of pages */
PFAULTHOOK    PageFaultHandlerFcnPtr;  /*  Page fault handler function */
BOOL          OptionFlag;              /*  Options bit flag */
BOOL          rc;
 
rc = VDHInstallFaultHook(VDMHandle, StartingAddress,
      Pages, PageFaultHandlerFcnPtr, OptionFlag);</pre>
 
 
 
 
=== VDHInstallFaultHook Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) DOS session handle. If the parameter contains a 0 (zero), use the currently active DOS session.
 
 
 
 
 
=== VDHInstallFaultHook Parameter - StartingAddress ===
 
'''StartingAddress'''(PVOID) Starting linear address.
 
 
 
 
 
=== VDHInstallFaultHook Parameter - Pages ===
 
'''Pages'''(ULONG) Number of pages.
 
 
 
 
 
=== VDHInstallFaultHook Parameter - PageFaultHandlerFcnPtr ===
 
'''PageFaultHandlerFcnPtr'''(PFAULTHOOK) Page fault handler function.
 
The PageFaultHandlerFcnPtr function pointer contains the address of a function with the following interface:
 
<pre class="western"> VOID  HOOKENTRY PageFaultHandler(pVDM)
      ENTRY PARAMETERS  pVDM - Address of the page in which fault occurred
      EXIT-SUCCESS      None
      EXIT-FAILURE      None
      CONTEXT          DOS session-task</pre>
 
 
 
 
 
 
=== VDHInstallFaultHook Parameter - OptionFlag ===
 
'''OptionFlag'''(BOOL) Options bit flag.
 
Possible value:
 
VDHIFH_ADDR If set, pVDM is a byte-granular address. Otherwise, pVDM is a page-granular address.
 
 
 
 
 
=== VDHInstallFaultHook Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If any of the input parameters are invalid, a system halt occurs.
 
 
 
 
 
=== VDHInstallFaultHook - Parameters ===
 
'''VDMHandle'''(HVDM) DOS session handle. If the parameter contains a 0 (zero), use the currently active DOS session.
 
'''StartingAddress'''(PVOID) Starting linear address.
 
'''Pages'''(ULONG) Number of pages.
 
'''PageFaultHandlerFcnPtr'''(PFAULTHOOK) Page fault handler function.
 
The PageFaultHandlerFcnPtr function pointer contains the address of a function with the following interface:
 
<pre class="western"> VOID  HOOKENTRY PageFaultHandler(pVDM)
      ENTRY PARAMETERS  pVDM - Address of the page in which fault occurred
      EXIT-SUCCESS      None
      EXIT-FAILURE      None
      CONTEXT          DOS session-task</pre>
 
 
'''OptionFlag'''(BOOL) Options bit flag.
 
Possible value:
 
VDHIFH_ADDR If set, pVDM is a byte-granular address. Otherwise, pVDM is a page-granular address.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If any of the input parameters are invalid, a system halt occurs.
 
 
 
 
 
=== VDHInstallFaultHook - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: Any fault hooks for the terminating DOS session must be released by using VDHRemoveFaultHook.
 
Notes: In order for the fault handler to terminate the DOS session, it must call VDHKillVDM and return. Page fault hooks are stored on a per-DOS session basis.
 
 
 
 
 
=== VDHInstallFaultHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHInstallIntHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function sets a handler for a V86 interrupt. The virtual device driver 's interrupt handler gets control after any subsequently hooked DOS interrupt handlers.
 
<pre class="western">#include mvdm.h
 
ULONG      Reserved;    /*  Reserved; must be set to 0 */
ULONG      Vector;      /*  Number of the interrupt vector to hook */
PFNHOOK    HookFcn;    /*  Address of the hook routine */
FLAGS      OptionFlag;  /*  Interface options flag */
BOOL      rc;
 
rc = VDHInstallIntHook(Reserved, Vector, HookFcn,
      OptionFlag);</pre>
 
 
 
 
=== VDHInstallIntHook - Format ===
 
This function sets a handler for a V86 interrupt. The virtual device driver 's interrupt handler gets control after any subsequently hooked DOS interrupt handlers.
 
<pre class="western">#include mvdm.h
 
ULONG      Reserved;    /*  Reserved; must be set to 0 */
ULONG      Vector;      /*  Number of the interrupt vector to hook */
PFNHOOK    HookFcn;    /*  Address of the hook routine */
FLAGS      OptionFlag;  /*  Interface options flag */
BOOL      rc;
 
rc = VDHInstallIntHook(Reserved, Vector, HookFcn,
      OptionFlag);</pre>
 
 
 
 
=== VDHInstallIntHook Parameter - Reserved ===
 
'''Reserved'''(ULONG) Reserved. Must be set to 0.
 
 
 
 
 
=== VDHInstallIntHook Parameter - Vector ===
 
'''Vector'''(ULONG) Number of the interrupt vector to hook (0-255).
 
 
 
 
 
=== VDHInstallIntHook Parameter - HookFcn ===
 
'''HookFcn'''(PFNHOOK) Address of the hook routine.
 
 
 
 
 
=== VDHInstallIntHook Parameter - OptionFlag ===
 
'''OptionFlag'''(FLAGS) Interface options flag.
 
Possible values:
 
VDH_ASM_HOOK Use assembler language hook interface (for the assembler language interface refer to the function [[00583.htm|VDHInstallIOHook]]). Otherwise, use the calling convention in the function prototype VDHENTRY found in the MVDM .INC include file, which is included with the Toolkit.
 
VDH_PRE_HOOK If set, install handler as a pre-reflection hook; that is, call the hook routine before reflecting the interrupt to V86 mode.
 
C Language Interface for the interrupt hook routine:
 
<pre class="western"> HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  EBX - pcrf - Client register frame pointer
;    EXIT  If carry flag set, chain to next virtual device driver
;            If carry flag clear, don't chain to the next virtual
;            device driver
;    USES  EAX, ECX, EDX, FS, GS, Flags
;  CONTEXT  DOS Session-task</pre>
 
 
 
 
 
 
=== VDHInstallIntHook Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''HookFcn''is invalid or if ''Vector''is out of range, a system halt occurs.
 
 
 
 
 
=== VDHInstallIntHook - Parameters ===
 
'''Reserved'''(ULONG) Reserved. Must be set to 0.
 
'''Vector'''(ULONG) Number of the interrupt vector to hook (0-255).
 
'''HookFcn'''(PFNHOOK) Address of the hook routine.
 
'''OptionFlag'''(FLAGS) Interface options flag.
 
Possible values:
 
VDH_ASM_HOOK Use assembler language hook interface (for the assembler language interface refer to the function [[00583.htm|VDHInstallIOHook]]). Otherwise, use the calling convention in the function prototype VDHENTRY found in the MVDM .INC include file, which is included with the Toolkit.
 
VDH_PRE_HOOK If set, install handler as a pre-reflection hook; that is, call the hook routine before reflecting the interrupt to V86 mode.
 
C Language Interface for the interrupt hook routine:
 
<pre class="western"> HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  EBX - pcrf - Client register frame pointer
;    EXIT  If carry flag set, chain to next virtual device driver
;            If carry flag clear, don't chain to the next virtual
;            device driver
;    USES  EAX, ECX, EDX, FS, GS, Flags
;  CONTEXT  DOS Session-task</pre>
 
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''HookFcn''is invalid or if ''Vector''is out of range, a system halt occurs.
 
 
 
 
 
=== VDHInstallIntHook - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function. Interrupt hooks are automatically removed during DOS session termination.
 
Notes: The effect of this service is per-DOS session; the software interrupt handler must be installed as each DOS session is created. The return value from the interrupt hook controls whether the next virtual device driver is chained to or not. An explicit ''VDHPopInt''is needed to remove the software interrupt (so that the ROM code is not executed).
 
 
 
 
 
=== VDHInstallIntHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHInstallIOHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used to install I/O port hooks.
 
<pre class="western">#include mvdm.h
 
ULONG    Reserved;        /*  Reserved; must be set to 0 */
PORT    StartingPort;    /*  Starting port number */
ULONG    NumPorts;        /*  The number of ports from the starting point */
PIOH    IOPortHookEntry;  /*  Pointer to I/O port hook entry */
FLAGS    Flags;            /*  Indicates interface and trapping options */
BOOL    rc;
 
rc = VDHInstallIOHook(Reserved, StartingPort,
      NumPorts, IOPortHookEntry, Flags);</pre>
 
 
 
 
=== VDHInstallIOHook - Format ===
 
This function is used to install I/O port hooks.
 
<pre class="western">#include mvdm.h
 
ULONG    Reserved;        /*  Reserved; must be set to 0 */
PORT    StartingPort;    /*  Starting port number */
ULONG    NumPorts;        /*  The number of ports from the starting point */
PIOH    IOPortHookEntry;  /*  Pointer to I/O port hook entry */
FLAGS    Flags;            /*  Indicates interface and trapping options */
BOOL    rc;
 
rc = VDHInstallIOHook(Reserved, StartingPort,
      NumPorts, IOPortHookEntry, Flags);</pre>
 
 
 
 
=== VDHInstallIOHook Parameter - Reserved ===
 
'''Reserved'''(ULONG) Reserved. Must be set to 0 (zero).
 
 
 
 
 
=== VDHInstallIOHook Parameter - StartingPort ===
 
'''StartingPort'''(PORT) Number of the starting port.
 
 
 
 
 
=== VDHInstallIOHook Parameter - NumPorts ===
 
'''NumPorts'''(ULONG) The number of ports from the starting port.
 
 
 
 
 
=== VDHInstallIOHook Parameter - IOPortHookEntry ===
 
'''IOPortHookEntry'''(PIOH) Pointer to I/O port hook entry.
 
 
 
 
 
=== VDHInstallIOHook Parameter - Flags ===
 
'''Flags'''(FLAGS) Indicates interface and trapping options.
 
Possible values:
 
VDHIIH_ASM_HOOK Use assembler language hook interface (register-based). Otherwise, use a C hook interface (stack-based).
 
VDHIIH_ALWAYS_TRAP Always trap this range of addresses. The virtual device driver cannot call VDHSetIOHookState on any ports in the range.
 
VDHIIH_NO_SIMULATE Does not change WORD or other I/O handlers to simulation routines; allows WORD handlers for 1-port ranges.
 
VDHIIH_IGNORE Sets a system handler that does the following:
 
On WRITES: The OUT succeeds, but no actual I/O is performed. <br />On READS: The IN succeeds, and always returns -1 (all bits set to 1).
 
This is also the default behavior of unhooked ports. This behavior is compatible with the behavior of a machine when there is no hardware on a particular I/O address.
 
 
 
 
 
=== VDHInstallIOHook Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''IOPortHookEntry''is invalid, or if ''StartingPort''or ''NumPorts''are out of range, a system halt occurs.
 
 
 
 
 
=== VDHInstallIOHook - Parameters ===
 
'''Reserved'''(ULONG) Reserved. Must be set to 0 (zero).
 
'''StartingPort'''(PORT) Number of the starting port.
 
'''NumPorts'''(ULONG) The number of ports from the starting port.
 
'''IOPortHookEntry'''(PIOH) Pointer to I/O port hook entry.
 
'''Flags'''(FLAGS) Indicates interface and trapping options.
 
Possible values:
 
VDHIIH_ASM_HOOK Use assembler language hook interface (register-based). Otherwise, use a C hook interface (stack-based).
 
VDHIIH_ALWAYS_TRAP Always trap this range of addresses. The virtual device driver cannot call VDHSetIOHookState on any ports in the range.
 
VDHIIH_NO_SIMULATE Does not change WORD or other I/O handlers to simulation routines; allows WORD handlers for 1-port ranges.
 
VDHIIH_IGNORE Sets a system handler that does the following:
 
On WRITES: The OUT succeeds, but no actual I/O is performed. <br />On READS: The IN succeeds, and always returns -1 (all bits set to 1).
 
This is also the default behavior of unhooked ports. This behavior is compatible with the behavior of a machine when there is no hardware on a particular I/O address.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''IOPortHookEntry''is invalid, or if ''StartingPort''or ''NumPorts''are out of range, a system halt occurs.
 
 
 
 
 
=== VDHInstallIOHook - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function. I/O hooks are automatically removed during DOS session termination.
 
Notes: This function installs I/O port trap handlers for a contiguous range of I/O addresses. Trapping is initially enabled for the specified ports. The I/O hook entry contains the handlers for each kind of I/O operation. If an entry in the table is NULL, that I/O type is simulated by using a lower I/O type (for example, WORD-I/O is simulated by performing two-byte I/O operations). I/O port hooks are kept on a per-DOS session basis; a virtual device driver generally installs I/O hooks at DOS session creation time.
 
VDHSetIOHookState can be used to enable or disable I/O trapping on a per- port, per-DOS session basis except when the VDHIIH_ALWAYS_TRAP option is specified. In this case, VDHSetIOHookState cannot be called on any port in the range for the current DOS session.
 
I/O hooks can take their parameters either from registers or the stack. High-performance hooks take register parameters (the I/O hook router is optimized for this case). Hooks with lower performance requirements take stack parameters, and therefore can be written in the C language.
 
WordInput, WordOutput and Other hooks can be NULL. In this case, the DOS Session Manager simulates these routines by using the ByteInput and ByteOutput routines. If the ByteInput or ByteOutput handlers are NULL, the DOS Session Manager uses default internal routines that do input and output to the hardware ports. This is most useful when a virtual device driver shadows the hardware state (by trapping OUT instructions) but does not care what is returned by IN instructions.
 
The client register frame (CRF) is updated as the instructions are simulated. For example, when the string I/O instructions are simulated, the client's EDI/ESI and ECX is incremented or decremented.
 
In a particular DOS session, a particular I/O port address can be hooked only by a single virtual device driver. If this function fails, no I/O hooks are installed.
 
The routing of I/O instructions to the supplied port hooks covers the specified range exactly. If an I/O instruction overlaps port address ranges hooked on separate VDHInstallIOHook calls, the instruction is simulated with smaller I/O operations to ensure that the hooks in each range are called correctly. For example, a virtual device driver that hooks 100H-103H , and installs a byte, WORD, and DWORD (other) handler would work as follows:
 
<pre class="western">    VDHInstallIOHook (reserved,0x100,4,&amp;iohA,NULL);</pre>
The I/O instructions to each address with the length indicated cause the following hooks to be called:
 
<pre class="western">/--------------------------------------------------------------\
|Address        |Length        |Hooks Called                  |
|---------------+---------------+------------------------------|
|  100          |  4          |iohA.Other(100,DWORD)        |
|---------------+---------------+------------------------------|
|  101          |  4          |iohA.Word(101) iohA.Byte(103) |
|---------------+---------------+------------------------------|
|  102          |  4          |iohA.Word(102)                |
|---------------+---------------+------------------------------|
|  103          |  4          |iohA.Byte(103)                |
\--------------------------------------------------------------/</pre>
VDHRemoveIOHook must be called with identical StartingPort and NumPorts in order to remove these I/O hooks. Port hooks cannot be removed for a subset of the range of ports hooked on the call to VDHInstallIOHook. If the IOPortHookEntry is in instance data, the address passed to VDHInstallIOHook must be the same address passed to VDHRemoveIOHook or VDHSetIOHookState.
 
Virtual device drivers hook ports in all cases, even if the desired behavior is to act as though direct port access were allowed. This keeps the I/O Permissions Map small. Only a port that requires high performance ( for example, a graphics card) is allowed to go straight through. The existence of such ports increases the size of the I/O Permissions Map in the Task State segment even if SetIOHookState is never called for them.
 
Interfaces for IOPortHookEntry are as follows:
 
<pre class="western">typedef struct ioh {
    PBIH ioh_pbihByteInput;
    PBOH ioh_pbohByteOutput;
    PWIH ioh_pwihWordInput;
    PWOH ioh_pwohWordOutput;
    POTH ioh_pothOther;
} IOH;</pre>
 
 
<pre class="western">BYTE HOOKENTRY ByteInput(port, pcrf)
    ENTRY    port                  - Port number
            pcrf                  - Client register frame pointer
    EXIT    Returns data read
    USES    EAX, ECX, EDX, FS, GS, Flags
    CONTEXT  DOS session-task</pre>
 
 
<pre class="western">BYTE HOOKENTRY ByteOutput(bOutputData, port, pcrf)
    ENTRY    bOutputData    - Data to write
            port            - Port number
            pcrf            - Client register frame pointer
    EXIT    None
    USES    EAX, ECX, EDX, FS, GS, Flags
    CONTEXT  DOS session-task</pre>
 
 
<pre class="western">USHORT HOOKENTRY WordInput(port, pcrf)
    ENTRY    port                - Port number
            pcrf                - Client register frame pointer
    EXIT    Returns data read
    USES    EAX, ECX, EDX, FS, GS, Flags
    CONTEXT  DOS session-task</pre>
 
 
<pre class="western">USHORT HOOKENTRY WordOutput(usOutputData, port, pcrf)
    ENTRY    usOutputData          - Data to write
            port                  - Port number
            pcrf                  - Client register frame pointer
    EXIT    None
    USES    EAX, ECX, EDX, FS, GS, Flags
    CONTEXT  DOS session-task</pre>
 
 
<pre class="western">ULONG HOOKENTRY Other(ulOutputData, pulInputData, port, flType, pcrf)
    ENTRY    ulOutputData              - Data for DWORD writes
            pulInputData              - Pointer to put input data
            port                      - Port number
            flType                    - I/O type
                IO_TYPE_SHIFT        - Shift for type
                IO_TYPE_MASK        - Mask for type
                IO_TYPE_INPUT        - If set input else output
                IO_TYPE_BYTE        - If set byte else WORD/DWORD
                IO_TYPE_DWORD
                IO_TYPE_STRING
                IO_TYPE_REVERSE
                IO_TYPE_ADDR32
                IO_TYPE_REP
                IO_SEG_SHIFT        - Shift for SEG  field
                IO_SEG_MASK          - Mask for SEG field
                IO_SEG_CS
                IO_SEG_SS
                IO_SEG_ES
                IO_SEG_FS
                IO_SEG_GS
            pcrf                      - Client register frame pointer
    EXIT        *pulInputData          - Data from DWORD reads
                if returns 0, simulate the I/O operation
                if returns a nonzero value, I/O is done
    USES    EAX, ECX, EDX, FS, GS, Flags
    CONTEXT  DOS session-task
    NOTES    (1) The ASM Other hook does not need the pulInputData
                parameter because it returns DWORD input values in EAX,
                with the carry flag used to indicate done/simulate. See
                &quot;VDHInstallIOHook&quot; in Assembler Language Syntax.
 
                The C hook has to use EAX to return status, and so needs
                the additional parameter.</pre>
 
 
 
 
=== VDHInstallIOHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHInstallUserHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used to set a handler for a specific DOS session event.
 
<pre class="western">#include mvdm.h
 
ULONG        Event;    /*  A DOS session event for which a handler is installed */
PUSERHOOK    UserHook;  /*  User's handler for this event */
BOOL        rc;
 
rc = VDHInstallUserHook(Event, UserHook);</pre>
 
 
 
 
=== VDHInstallUserHook - Format ===
 
This function is used to set a handler for a specific DOS session event.
 
<pre class="western">#include mvdm.h
 
ULONG        Event;    /*  A DOS session event for which a handler is installed */
PUSERHOOK    UserHook;  /*  User's handler for this event */
BOOL        rc;
 
rc = VDHInstallUserHook(Event, UserHook);</pre>
 
 
 
 
=== VDHInstallUserHook Parameter - Event ===
 
'''Event'''(ULONG) A DOS session event (such as DOS session termination).
 
Possible values are:
 
VDD_EXIT DOS session support is shutting down <br />VDM_CREATE DOS session creation <br />VDM_TERMINATE DOS session termination <br />VDM_FOREGROUND DOS session to the foreground <br />VDM_BACKGROUND DOS session to the background <br />VDM_CREATE_DONE DOS session creation completed successfully <br />VDM_VDD_CREATE_DONE DOS session virtual device driver creation completed <br />VDM_PDB_DESTROY DOS Program Data Block (PDB) destroyed in DOS session <br />VDM_PDB_CHANGE PDB changed in DOS session <br />VDM_CODEPAGE_CHANGE Code page change event <br />VDM_TITLE_CHANGE DOS session title change event <br />VDM_MEMORY_MAPPED_IN Pages mapped into a DOS session (0 to 1MB+64KB) <br />VDM_MEMORY_UN_MAPPED Pages unmapped from a DOS session (0 to 1MB+64KB). <br />VDM_BEGIN_VPM_TASK Protected-mode task has started <br />VDM_END_VPM_TASK Protected-mode task has ended
 
The interfaces for the ''UserHook''handlers (depending on the event that is handled) are:
 
<pre class="western"> RETCODE HOOKENTRY pfnExit()
        ENTRY    None
        EXIT      None
        CONTEXT  INIT
                  Task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnCreate(hvdm)
        ENTRY        hvdm
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
                        DOS session creation fails; the DOS Session Manager
                        calls all the VD_TERMINATE hooks for all
                        virtual device drivers that returned Successful on this
                        DOS session creation.
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnTerminate(hvdm)
        ENTRY        hvdm - DOS session being terminated
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnForeground(hvdm)
        ENTRY    hvdm - DOS session coming foreground
        EXIT      None
        CONTEXT  Task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnBackground(hvdm)
        ENTRY    hvdm - DOS session going background
        EXIT      None
        CONTEXT  Task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnCreateDone(hvdm)
        ENTRY    hvdm
        EXIT      None
        CONTEXT  DOS session creation</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnVDDCreateDone(hvdm)
        ENTRY    hvdm
        EXIT      None
        CONTEXT  DOS session Creation</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnPDBDestroy(hvdm,segPDB)
        ENTRY        hvdm
                      segPDB  V86 segment of terminating PDB
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnPDBChange(hvdm,segPDB)
        ENTRY        hvdm
                      segPDB  V86 segment of new PDB
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> VOID HOOKENTRY pfnCodePageChange(ulCodePage)
      ENTRY        ulCodePage - New code page
      EXIT-SUCCESS  Return a nonzero value
      EXIT-FAILURE  Return 0
                      An error is returned on the set code-page operation, but
                      the rest of the device-code-page handlers are called.
      CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> VOID HOOKENTRY pfnVDMTitleChange (pszTitle)
      ENTRY        pszTitle  new DOS session Title
      EXIT-SUCCESS  Return a nonzero value
      EXIT-FAILURE  Return 0
      CONTEXT      DOS session-task
      NOTES        1. This event is called for both full screen and windowed
                      DOS session.
                    2. If pszTitle is NULL, the virtual device driver should
                      treat it as DOS session's default and original title.
                    3. Ideally there should be only one virtual device driver for this
                      hook, but this is not a restriction.  One of the
                      virtual device drivers registered is responsible for
                      putting the title.  Only this virtual device driver returns
                      a nonzero value; all others return 0.</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnMemoryMappedIn (hvdm,page,cpages,fl)
        ENTRY        hvdm
                      page    page address
                      cpages  # of pages mapped in from
                                the starting page address
                      fl      type of mapping, (see VDHMapPages)
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnMemoryUnMapped (hvdm,page,cpages,fl)
        ENTRY        hvdm
                      page    page address
                      cpages  # of pages unmapped from the starting page address
                      fl      type of mapping, (see VDHMapPages)
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnBeginVDMTask (hvdm,page,cpages,fl)
        ENTRY        hvdm
                      page    page address
                      cpages  # of pages unmapped from the starting page address
                      fl      type of mapping, (see VDHMapPages)
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnEndVDMTask (hvdm,page,cpages,fl)
        ENTRY        hvdm
                      page    page address
                      cpages  # of pages unmapped from the starting page address
                      fl      type of mapping, (see VDHMapPages)
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnBeginVPMTask (hvdm,page,cpages,fl)
        ENTRY        hvdm
                      page    page address
                      cpages  # of pages unmapped from the starting page address
                      fl      type of mapping, (see VDHMapPages)
        EXIT          None
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnEndVPMTask (hvdm,page,cpages,fl)
        ENTRY        hvdm
                      page    page address
                      cpages  # of pages unmapped from the starting page address
                      fl      type of mapping, (see VDHMapPages)
        EXIT          None
        CONTEXT      DOS session-task</pre>
 
 
 
 
 
 
=== VDHInstallUserHook Parameter - UserHook ===
 
'''UserHook'''(PUSERHOOK) A user-defined handler for the event.
 
 
 
 
 
=== VDHInstallUserHook Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, an invalid input parameter or a kernel heap overflow (that is, if the system runs out of memory) causes a system halt.
 
 
 
 
 
=== VDHInstallUserHook - Parameters ===
 
'''Event'''(ULONG) A DOS session event (such as DOS session termination).
 
Possible values are:
 
VDD_EXIT DOS session support is shutting down <br />VDM_CREATE DOS session creation <br />VDM_TERMINATE DOS session termination <br />VDM_FOREGROUND DOS session to the foreground <br />VDM_BACKGROUND DOS session to the background <br />VDM_CREATE_DONE DOS session creation completed successfully <br />VDM_VDD_CREATE_DONE DOS session virtual device driver creation completed <br />VDM_PDB_DESTROY DOS Program Data Block (PDB) destroyed in DOS session <br />VDM_PDB_CHANGE PDB changed in DOS session <br />VDM_CODEPAGE_CHANGE Code page change event <br />VDM_TITLE_CHANGE DOS session title change event <br />VDM_MEMORY_MAPPED_IN Pages mapped into a DOS session (0 to 1MB+64KB) <br />VDM_MEMORY_UN_MAPPED Pages unmapped from a DOS session (0 to 1MB+64KB). <br />VDM_BEGIN_VPM_TASK Protected-mode task has started <br />VDM_END_VPM_TASK Protected-mode task has ended
 
The interfaces for the ''UserHook''handlers (depending on the event that is handled) are:
 
<pre class="western"> RETCODE HOOKENTRY pfnExit()
        ENTRY    None
        EXIT      None
        CONTEXT  INIT
                  Task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnCreate(hvdm)
        ENTRY        hvdm
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
                        DOS session creation fails; the DOS Session Manager
                        calls all the VD_TERMINATE hooks for all
                        virtual device drivers that returned Successful on this
                        DOS session creation.
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnTerminate(hvdm)
        ENTRY        hvdm - DOS session being terminated
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnForeground(hvdm)
        ENTRY    hvdm - DOS session coming foreground
        EXIT      None
        CONTEXT  Task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnBackground(hvdm)
        ENTRY    hvdm - DOS session going background
        EXIT      None
        CONTEXT  Task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnCreateDone(hvdm)
        ENTRY    hvdm
        EXIT      None
        CONTEXT  DOS session creation</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnVDDCreateDone(hvdm)
        ENTRY    hvdm
        EXIT      None
        CONTEXT  DOS session Creation</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnPDBDestroy(hvdm,segPDB)
        ENTRY        hvdm
                      segPDB  V86 segment of terminating PDB
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnPDBChange(hvdm,segPDB)
        ENTRY        hvdm
                      segPDB  V86 segment of new PDB
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> VOID HOOKENTRY pfnCodePageChange(ulCodePage)
      ENTRY        ulCodePage - New code page
      EXIT-SUCCESS  Return a nonzero value
      EXIT-FAILURE  Return 0
                      An error is returned on the set code-page operation, but
                      the rest of the device-code-page handlers are called.
      CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> VOID HOOKENTRY pfnVDMTitleChange (pszTitle)
      ENTRY        pszTitle  new DOS session Title
      EXIT-SUCCESS  Return a nonzero value
      EXIT-FAILURE  Return 0
      CONTEXT      DOS session-task
      NOTES        1. This event is called for both full screen and windowed
                      DOS session.
                    2. If pszTitle is NULL, the virtual device driver should
                      treat it as DOS session's default and original title.
                    3. Ideally there should be only one virtual device driver for this
                      hook, but this is not a restriction.  One of the
                      virtual device drivers registered is responsible for
                      putting the title.  Only this virtual device driver returns
                      a nonzero value; all others return 0.</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnMemoryMappedIn (hvdm,page,cpages,fl)
        ENTRY        hvdm
                      page    page address
                      cpages  # of pages mapped in from
                                the starting page address
                      fl      type of mapping, (see VDHMapPages)
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnMemoryUnMapped (hvdm,page,cpages,fl)
        ENTRY        hvdm
                      page    page address
                      cpages  # of pages unmapped from the starting page address
                      fl      type of mapping, (see VDHMapPages)
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnBeginVDMTask (hvdm,page,cpages,fl)
        ENTRY        hvdm
                      page    page address
                      cpages  # of pages unmapped from the starting page address
                      fl      type of mapping, (see VDHMapPages)
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnEndVDMTask (hvdm,page,cpages,fl)
        ENTRY        hvdm
                      page    page address
                      cpages  # of pages unmapped from the starting page address
                      fl      type of mapping, (see VDHMapPages)
        EXIT-SUCCESS  Return a nonzero value
        EXIT-FAILURE  Return 0
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnBeginVPMTask (hvdm,page,cpages,fl)
        ENTRY        hvdm
                      page    page address
                      cpages  # of pages unmapped from the starting page address
                      fl      type of mapping, (see VDHMapPages)
        EXIT          None
        CONTEXT      DOS session-task</pre>
 
 
<pre class="western"> RETCODE HOOKENTRY pfnEndVPMTask (hvdm,page,cpages,fl)
        ENTRY        hvdm
                      page    page address
                      cpages  # of pages unmapped from the starting page address
                      fl      type of mapping, (see VDHMapPages)
        EXIT          None
        CONTEXT      DOS session-task</pre>
 
 
'''UserHook'''(PUSERHOOK) A user-defined handler for the event.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, an invalid input parameter or a kernel heap overflow (that is, if the system runs out of memory) causes a system halt.
 
 
 
 
 
=== VDHInstallUserHook - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Sessions Terminations: The VDM_TERMINATE hook is called at DOS session termination. In the case of a partially created DOS session, the VDM_ TERMINATE handler is called only if all the registered VDM_CREATE handlers are called successfully. Partially created DOS sessions might occur when, for example, the ''Create_Handler''for Virtual Device Driver A returned successfully, but the ''Create_Handler''for Virtual Device Driver B failed. In this case, the ''Terminate_Handler''for Virtual Device Driver A will not be called. This should be taken into consideration when deciding what to do in a ''Create_Handler''and a ''Create_Done_Handler''.
 
 
 
 
 
=== VDHInstallUserHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHIsVDMFrozen ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns the freeze state of a DOS session.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Handle to the DOS session */
BOOL    rc;
 
rc = VDHIsVDMFrozen(VDMHandle);</pre>
 
 
 
 
=== VDHIsVDMFrozen - Format ===
 
This function returns the freeze state of a DOS session.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Handle to the DOS session */
BOOL    rc;
 
rc = VDHIsVDMFrozen(VDMHandle);</pre>
 
 
 
 
=== VDHIsVDMFrozen Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session in question.
 
 
 
 
 
=== VDHIsVDMFrozen Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the DOS session is not frozen, the function returns 0 (zero). Otherwise, the function returns a nonzero value indicating the DOS session' s freeze count.
 
Failure If ''VDMHandle''is an invalid DOS session handle, a system halt occurs .
 
 
 
 
 
=== VDHIsVDMFrozen - Parameters ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session in question.
 
'''rc'''(BOOL) - returns
 
Success If the DOS session is not frozen, the function returns 0 (zero). Otherwise, the function returns a nonzero value indicating the DOS session' s freeze count.
 
Failure If ''VDMHandle''is an invalid DOS session handle, a system halt occurs .
 
 
 
 
 
=== VDHIsVDMFrozen - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: See [[00477.htm|VDHFreezeVDM]]for a full discussion of freeze counting.
 
 
 
 
 
=== VDHIsVDMFrozen - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHKillVDM ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function terminates the DOS session at the earliest opportunity. V86 code is no longer executed in the context of the terminated DOS session.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Handle to the DOS session to terminate */
 
VDHKillVDM(VDMHandle);</pre>
 
 
 
 
=== VDHKillVDM - Format ===
 
This function terminates the DOS session at the earliest opportunity. V86 code is no longer executed in the context of the terminated DOS session.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Handle to the DOS session to terminate */
 
VDHKillVDM(VDMHandle);</pre>
 
 
 
 
=== VDHKillVDM Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session to terminate. A value of 0 (zero ) indicates the current DOS session.
 
 
 
 
 
=== VDHKillVDM - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''VDMHandle''is not a valid DOS session handle, a system halt occurs.
 
 
 
 
 
=== VDHKillVDM - Parameters ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session to terminate. A value of 0 (zero ) indicates the current DOS session.
 
Success If the function is successful, it returns nothing.
 
Failure If ''VDMHandle''is not a valid DOS session handle, a system halt occurs.
 
 
 
 
 
=== VDHKillVDM - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: When a DOS session is terminating, all virtual device drivers that registered a VDM_TERMINATE hook by using ''VDHInstallUserHook''are called.
 
Notes: This function sets a flag and returns. If the calling virtual device driver is in the context of the DOS session to be terminated, it must return to its caller in order for the termination to occur.
 
 
 
 
 
=== VDHKillVDM - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHLockMem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function verifies that a specified region is accessible in the requested manner, and locks the memory in the requested manner.
 
<pre class="western">#include mvdm.h
 
PVOID    StartingLinAddr;  /*  Starting address of region in user process */
ULONG    NumBytes;          /*  The size of the region to lock, in bytes. */
ULONG    OptionFlag;        /*  Access option flags */
ULONG    PagelistArrayPtr;  /*  Pointer to array of VDHPageList_s structures */
ULONG    ArrayCountPtr;    /*  Points to count of VDHPageList_selements */
HLOCK    rc;
 
rc = VDHLockMem(StartingLinAddr, NumBytes,
      OptionFlag, PagelistArrayPtr, ArrayCountPtr);</pre>
 
 
 
 
=== VDHLockMem - Format ===
 
This function verifies that a specified region is accessible in the requested manner, and locks the memory in the requested manner.
 
<pre class="western">#include mvdm.h
 
PVOID    StartingLinAddr;  /*  Starting address of region in user process */
ULONG    NumBytes;          /*  The size of the region to lock, in bytes. */
ULONG    OptionFlag;        /*  Access option flags */
ULONG    PagelistArrayPtr;  /*  Pointer to array of VDHPageList_s structures */
ULONG    ArrayCountPtr;    /*  Points to count of VDHPageList_selements */
HLOCK    rc;
 
rc = VDHLockMem(StartingLinAddr, NumBytes,
      OptionFlag, PagelistArrayPtr, ArrayCountPtr);</pre>
 
 
 
 
=== VDHLockMem Parameter - StartingLinAddr ===
 
'''StartingLinAddr'''(PVOID) Starting linear address of the region in the user process that is to be locked.
 
 
 
 
 
=== VDHLockMem Parameter - NumBytes ===
 
'''NumBytes'''(ULONG) Size in bytes of the region to lock.
 
 
 
 
 
=== VDHLockMem Parameter - OptionFlag ===
 
'''OptionFlag'''(ULONG) Used to set access options for the locked region. The VDHLM_READ and VDHLM_WRITE flags are for verification purposes and are not mixed with the VDHLM_RESIDENT flag. Either the VDHLM_READ, VDHLM_WRITE, or VDHLM_RESIDENT flag must be used. Note that VDHLM_RESIDENT cannot be combined with other flags.
 
Possible values are:
 
VDHLM_RESIDENT Lock physical pages.
 
VDHLM_READ Verify read access. VDHLM_READ is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.
 
VDHLM_WRITE Verify write access. VDHLM_WRITE is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.
 
VDHLM_CONTIGUOUS Force physical pages contiguous; can be used only for 64KB or less.
 
VDHLM_NOBLOCK Lock must not give up the CPU.
 
VDHLM_16M Must reside below the 16MB physical memory address.
 
 
 
 
 
=== VDHLockMem Parameter - PagelistArrayPtr ===
 
'''PagelistArrayPtr'''(ULONG) Pointer to array of VDHPageList_s structures.
 
''VDHLockMem''fills this array. Each ''VDHPageList_s''structure describes a single physically contiguous sub-area of the physical memory that was locked. If ''PagelistArrayPtr''is set to VDHLM_NO_ADDR, no array is returned. The area that ''PagelistArrayPtr''points to must contain enough ''VDHPageList_s''structures to handle a worst case of one structure per page plus one more structure, that is, the region does not begin on a page boundary.
 
 
 
 
 
=== VDHLockMem Parameter - ArrayCountPtr ===
 
'''ArrayCountPtr'''(ULONG) Pointer to a variable where a count of the number of elements returned in the ''PagelistArrayPtr''array is placed by ''VDHLockMem''. If ''PagelistArrayPtr''is set to VDHLM_NO_ADDR, ''ArrayCountPtr''is ignored.
 
 
 
 
 
=== VDHLockMem Return Value - rc ===
 
'''rc'''(HLOCK) - returns
 
Success If the function is successful, it returns a lock handle. This is a global handle that can be used in any task context.
 
Failure If the function fails, it returns 0. If the function fails, call ''VDHGetError''to determine the nature of the problem. If ''NumBytes''equals 0, a system halt occurs.
 
 
 
 
 
=== VDHLockMem - Parameters ===
 
'''StartingLinAddr'''(PVOID) Starting linear address of the region in the user process that is to be locked.
 
'''NumBytes'''(ULONG) Size in bytes of the region to lock.
 
'''OptionFlag'''(ULONG) Used to set access options for the locked region. The VDHLM_READ and VDHLM_WRITE flags are for verification purposes and are not mixed with the VDHLM_RESIDENT flag. Either the VDHLM_READ, VDHLM_WRITE, or VDHLM_RESIDENT flag must be used. Note that VDHLM_RESIDENT cannot be combined with other flags.
 
Possible values are:
 
VDHLM_RESIDENT Lock physical pages.
 
VDHLM_READ Verify read access. VDHLM_READ is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.
 
VDHLM_WRITE Verify write access. VDHLM_WRITE is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.
 
VDHLM_CONTIGUOUS Force physical pages contiguous; can be used only for 64KB or less.
 
VDHLM_NOBLOCK Lock must not give up the CPU.
 
VDHLM_16M Must reside below the 16MB physical memory address.
 
'''PagelistArrayPtr'''(ULONG) Pointer to array of VDHPageList_s structures.
 
''VDHLockMem''fills this array. Each ''VDHPageList_s''structure describes a single physically contiguous sub-area of the physical memory that was locked. If ''PagelistArrayPtr''is set to VDHLM_NO_ADDR, no array is returned. The area that ''PagelistArrayPtr''points to must contain enough ''VDHPageList_s''structures to handle a worst case of one structure per page plus one more structure, that is, the region does not begin on a page boundary.
 
'''ArrayCountPtr'''(ULONG) Pointer to a variable where a count of the number of elements returned in the ''PagelistArrayPtr''array is placed by ''VDHLockMem''. If ''PagelistArrayPtr''is set to VDHLM_NO_ADDR, ''ArrayCountPtr''is ignored.
 
'''rc'''(HLOCK) - returns
 
Success If the function is successful, it returns a lock handle. This is a global handle that can be used in any task context.
 
Failure If the function fails, it returns 0. If the function fails, call ''VDHGetError''to determine the nature of the problem. If ''NumBytes''equals 0, a system halt occurs.
 
 
 
 
 
=== VDHLockMem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function. There cannot be any memory locked on behalf of a particular DOS session.
 
Notes: The caller must call ''VDHUnlockMem''to remove this lock. All locks are long-term. This function must be used prior to using any pointers passed to a virtual device driver from an OS/2 process (through ''DOSRequestVDD''). This might also be useful to the callers of ''VDHCopyMem''and ''VDHExchangeMem''.
 
''VDHMapPages'', ''VDHReallocPages'', and ''VDHFreePages''will block if applied to pages that are locked. They unblock when the lock is released.
 
 
 
 
 
=== VDHLockMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHMapPages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function maps a linear address region in the V86 address space.
 
<pre class="western">#include mvdm.h
 
PVDHMAPSOURCE    pvdhmsSourceRegion;  /*  Pointer to source region definition */
PVDHMAPTARGET    pvdhmtTargetRegion;  /*  Target region definition */
ULONG            flMappingFlag;      /*  Mapping options flag */
BOOL            rc;
 
rc = VDHMapPages(pvdhmsSourceRegion, pvdhmtTargetRegion,
      flMappingFlag);</pre>
 
 
 
 
=== VDHMapPages - Format ===
 
This function maps a linear address region in the V86 address space.
 
<pre class="western">#include mvdm.h
 
PVDHMAPSOURCE    pvdhmsSourceRegion;  /*  Pointer to source region definition */
PVDHMAPTARGET    pvdhmtTargetRegion;  /*  Target region definition */
ULONG            flMappingFlag;      /*  Mapping options flag */
BOOL            rc;
 
rc = VDHMapPages(pvdhmsSourceRegion, pvdhmtTargetRegion,
      flMappingFlag);</pre>
 
 
 
 
=== VDHMapPages Parameter - pvdhmsSourceRegion ===
 
'''pvdhmsSourceRegion'''(PVDHMAPSOURCE) Pointer to VDHMAPSOURCE structure.
 
VDHMAPSOURCE is the source region definition for ''VDHMapPages''with a data structure as follows:
 
<pre class="western">typedef struct VDHMapSource_s {
    ULONG  vdhms_laddr;    /* Source linear address of source */
                            /* memory object.  Source address  */
                            /* to be mapped.  Defines the start*/
                            /* of the source region for the    */
                            /* mapping.  The region is the same*/
                            /* length as the target region.    */
    ULONG  vdhms_hobj;      /* Memory object handle set by the */
                            /* service to hold a source handle */
                            /* for VDHMT_LINEAR mappings.      */
                            /* See the VDHMT_LINEAR            */
                            /* description under MappingFlag.  */
} VDHMAPSOURCE;
typedef VDHMAPSOURCE *PVDHMAPSOURCE;</pre>
 
 
 
 
 
 
=== VDHMapPages Parameter - pvdhmtTargetRegion ===
 
'''pvdhmtTargetRegion'''(PVDHMAPTARGET) Target region definition. Pointer to VDHMAPTARGET structure.
 
VDHMAPTARGET is the target region definition for ''VDHMapPages''with a data structure as follows:
 
<pre class="western">typedef struct VDHMapTarget_s {
    ULONG  vdhmt_laddr;    /* Address in V86-space to be      */
                            /* mapped.                        */
                            /* (0 &lt;= vdhmt_laddr &lt; 1MB+64KB)  */
    ULONG  vdhmt_cpg;      /* Count of pages to map.          */
    ULONG  vdhmt_hmap;      /* Mapping handle. Must be zero on */
                            /* the first call to VDHMapPages  */
                            /* for region.  Set by the service */
                            /* to hold a handle used for      */
                            /* remapping the region. The handle*/
                            /* is reset each time it is used.  */
                            /* vdhmt_hmap must be the value    */
                            /* returned from the previous      */
                            /* VDHMapPages call for the region */
                            /* unless the pages are either    */
                            /* already invalid or else are    */
                            /* being made invalid.  If either  */
                            /* the old or new mapping is      */
                            /* invalid pages, vdhmt_hmap can  */
                            /* be 0.                          */
                            /* Making a region invalid restores*/
                            /* pages in the region to their    */
                            /* reserved state, and sets        */
                            /* vdhmt_hmap to 0.                */
} VDHMAPTARGET;
 
typedef VDHMAPTARGET *PVDHMAPTARGET;</pre>
 
 
 
 
 
 
=== VDHMapPages Parameter - flMappingFlag ===
 
'''flMappingFlag'''(ULONG) Mapping options flag.
 
Possible values are:
 
VDHMT_INVALID Make target region pages invalid. ''vdhmt_hmap''can be 0 (zero). This service is faster when the handle is provided, but virtual device drivers that do not store handles can map to invalid before remapping a region. Note that ''pvdhmsSourceRegion''is ignored.
 
VDHMT_LINEAR Map linear source region into target region. ''vdhms_laddr''contains the linear address to map at the start of the target region. This can only be a page-granular address in a memory allocation that was obtained by using ''VDHAllocPages''or ''VDHReallocPages''. After a successful mapping, the target region aliases the corresponding region of the source.
 
''vdhms_hobj''must be 0 (zero) the first time a newly allocated or reallocated source object is mapped. On a successful mapping, ''vdhms_hobj''is filled in. Using this handle on the next mapping that uses the same source object speeds up that mapping call. Any linear address (''laddr'') at the start of the target region can be mapped using the handle. The returned result must be stored after each mapping call. Virtual device drivers can avoid storing this handle and always use 0 (zero), however, the call will be slower.
 
VDHMT_PHYSICAL Map physical source region into target region. ''vdhms_laddr''contains the physical address to map at the start of the target region. ''vdhms_hobj''is ignored.
 
VDHMT_BLACK_HOLE Map target region to black hole pages. ''pvdhmsSourceRegion''is ignored.
 
 
 
 
 
=== VDHMapPages Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHMapPages - Parameters ===
 
'''pvdhmsSourceRegion'''(PVDHMAPSOURCE) Pointer to VDHMAPSOURCE structure.
 
VDHMAPSOURCE is the source region definition for ''VDHMapPages''with a data structure as follows:
 
<pre class="western">typedef struct VDHMapSource_s {
    ULONG  vdhms_laddr;    /* Source linear address of source */
                            /* memory object.  Source address  */
                            /* to be mapped.  Defines the start*/
                            /* of the source region for the    */
                            /* mapping.  The region is the same*/
                            /* length as the target region.    */
    ULONG  vdhms_hobj;      /* Memory object handle set by the */
                            /* service to hold a source handle */
                            /* for VDHMT_LINEAR mappings.      */
                            /* See the VDHMT_LINEAR            */
                            /* description under MappingFlag.  */
} VDHMAPSOURCE;
typedef VDHMAPSOURCE *PVDHMAPSOURCE;</pre>
 
 
'''pvdhmtTargetRegion'''(PVDHMAPTARGET) Target region definition. Pointer to VDHMAPTARGET structure.
 
VDHMAPTARGET is the target region definition for ''VDHMapPages''with a data structure as follows:
 
<pre class="western">typedef struct VDHMapTarget_s {
    ULONG  vdhmt_laddr;    /* Address in V86-space to be      */
                            /* mapped.                        */
                            /* (0 &lt;= vdhmt_laddr &lt; 1MB+64KB)  */
    ULONG  vdhmt_cpg;      /* Count of pages to map.          */
    ULONG  vdhmt_hmap;      /* Mapping handle. Must be zero on */
                            /* the first call to VDHMapPages  */
                            /* for region.  Set by the service */
                            /* to hold a handle used for      */
                            /* remapping the region. The handle*/
                            /* is reset each time it is used.  */
                            /* vdhmt_hmap must be the value    */
                            /* returned from the previous      */
                            /* VDHMapPages call for the region */
                            /* unless the pages are either    */
                            /* already invalid or else are    */
                            /* being made invalid.  If either  */
                            /* the old or new mapping is      */
                            /* invalid pages, vdhmt_hmap can  */
                            /* be 0.                          */
                            /* Making a region invalid restores*/
                            /* pages in the region to their    */
                            /* reserved state, and sets        */
                            /* vdhmt_hmap to 0.                */
} VDHMAPTARGET;
 
typedef VDHMAPTARGET *PVDHMAPTARGET;</pre>
 
 
'''flMappingFlag'''(ULONG) Mapping options flag.
 
Possible values are:
 
VDHMT_INVALID Make target region pages invalid. ''vdhmt_hmap''can be 0 (zero). This service is faster when the handle is provided, but virtual device drivers that do not store handles can map to invalid before remapping a region. Note that ''pvdhmsSourceRegion''is ignored.
 
VDHMT_LINEAR Map linear source region into target region. ''vdhms_laddr''contains the linear address to map at the start of the target region. This can only be a page-granular address in a memory allocation that was obtained by using ''VDHAllocPages''or ''VDHReallocPages''. After a successful mapping, the target region aliases the corresponding region of the source.
 
''vdhms_hobj''must be 0 (zero) the first time a newly allocated or reallocated source object is mapped. On a successful mapping, ''vdhms_hobj''is filled in. Using this handle on the next mapping that uses the same source object speeds up that mapping call. Any linear address (''laddr'') at the start of the target region can be mapped using the handle. The returned result must be stored after each mapping call. Virtual device drivers can avoid storing this handle and always use 0 (zero), however, the call will be slower.
 
VDHMT_PHYSICAL Map physical source region into target region. ''vdhms_laddr''contains the physical address to map at the start of the target region. ''vdhms_hobj''is ignored.
 
VDHMT_BLACK_HOLE Map target region to black hole pages. ''pvdhmsSourceRegion''is ignored.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHMapPages - Purpose ===
 
This function maps a linear address region in the V86 address space to:
 
*Part of a virtual memory object <br />*Specific physical addresses (for physical devices) <br />*Undefined memory (black holes) <br />*Invalid pages (the unmapped state, which is the default state for reserved pages)
 
''VDHMapPages''also changes the virtual address contents of regions in the V86 address space (below 11000H (1MB+64KB)). Pages in this range can be made to address:
 
*Part of a memory object previously allocated using ''VDHAllocPages''or ''VDHReallocPages''<br />*Physical addresses for a device <br />*Black hole (undefined memory) addresses that are read or written but do not retain their values <br />*Invalid pages, which cause faults when accessed (see ''VDHInstallFaultHook'')
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Mapping succeeds only if it completely replaces a previous mapping, or if the region contains only invalid pages. To change the size of a region, it must first be made invalid. The entire target region must lie below 11000H (1MB+64KB) and must be contained in pages previously reserved by ''VDHReservePages''. ''VDHMapPages''and ''VDHAllocPages''can be used on the same target region but care must be taken. Before switching from one service to the other, the pages affected must first be made invalid. If pages are left invalid, a pagefault handler must be registered (through ''VDHInstallFaultHook'') to handle page faults, in case the pages are accessed.
 
Both target and source addresses must be on page boundaries. If they are not, the page offset part of the address is ignored.
 
 
 
 
 
=== VDHMapPages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHOpen ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function opens a file or device and returns a handle. The handle can be used with ''VDHRead'', ''VDHWrite'', ''VDHSeek'', ''VDHClose'',and ''VDHDevIOCtl''. The parameters and error return codes are the same as those found in the ''DosOpen''API. Refer to the ''OS/2 Control Program Programming Reference''for a complete descriptions of each ''DosOpen''API parameter.
 
<pre class="western">#include mvdm.h
 
PSZ          FileName;      /*  Pointer to the name of the file or device to open */
PHFILE      FileHandle;    /*  Where the system returns the file handle */
PULONG      ActionTaken;    /*  Where a description of the action taken is returned */
ULONG        FileSize;      /*  The new file's logical size (EOD) in bytes */
ULONG        FileAttribute;  /*  File attribute bits used on file creation */
ULONG        OpenFLag;      /*  Specifies action taken, based on whether file exists */
ULONG        OpenMode;      /*  Describes the mode of the Open function */
PVDH_EOAP    EABuf;          /*  Address of a VDH_EAOP structure or NULL */
BOOL        rc;
 
rc = VDHOpen(FileName, FileHandle, ActionTaken,
      FileSize, FileAttribute, OpenFLag,
      OpenMode, EABuf);</pre>
 
 
 
 
=== VDHOpen - Format ===
 
This function opens a file or device and returns a handle. The handle can be used with ''VDHRead'', ''VDHWrite'', ''VDHSeek'', ''VDHClose'',and ''VDHDevIOCtl''. The parameters and error return codes are the same as those found in the ''DosOpen''API. Refer to the ''OS/2 Control Program Programming Reference''for a complete descriptions of each ''DosOpen''API parameter.
 
<pre class="western">#include mvdm.h
 
PSZ          FileName;      /*  Pointer to the name of the file or device to open */
PHFILE      FileHandle;    /*  Where the system returns the file handle */
PULONG      ActionTaken;    /*  Where a description of the action taken is returned */
ULONG        FileSize;      /*  The new file's logical size (EOD) in bytes */
ULONG        FileAttribute;  /*  File attribute bits used on file creation */
ULONG        OpenFLag;      /*  Specifies action taken, based on whether file exists */
ULONG        OpenMode;      /*  Describes the mode of the Open function */
PVDH_EOAP    EABuf;          /*  Address of a VDH_EAOP structure or NULL */
BOOL        rc;
 
rc = VDHOpen(FileName, FileHandle, ActionTaken,
      FileSize, FileAttribute, OpenFLag,
      OpenMode, EABuf);</pre>
 
 
 
 
=== VDHOpen Parameter - FileName ===
 
'''FileName'''(PSZ) Pointer to the ASCIIZ string containing the name of the device or file to open.
 
 
 
 
 
=== VDHOpen Parameter - FileHandle ===
 
'''FileHandle'''(PHFILE) Where the system returns the file handle.
 
 
 
 
 
=== VDHOpen Parameter - ActionTaken ===
 
'''ActionTaken'''(PULONG) Where the system returns a description of the action taken as a result of this function call.
 
 
 
 
 
=== VDHOpen Parameter - FileSize ===
 
'''FileSize'''(ULONG) The new file's logical size (EOD) in bytes.
 
 
 
 
 
=== VDHOpen Parameter - FileAttribute ===
 
'''FileAttribute'''(ULONG) File attribute bits used on file creation.
 
 
 
 
 
=== VDHOpen Parameter - OpenFLag ===
 
'''OpenFLag'''(ULONG) Specifies the action taken depending on whether the file exists.
 
Possible actions are:
 
VDHOPEN_FILE_EXISTED File existed <br />VDHOPEN_FILE_CREATED File created <br />VDHOPEN_FILE_TRUNCATED File replaced
 
 
 
 
 
=== VDHOpen Parameter - OpenMode ===
 
'''OpenMode'''(ULONG) Describes the mode of the ''Open''function.
 
 
 
 
 
=== VDHOpen Parameter - EABuf ===
 
'''EABuf'''(PVDH_EOAP) Address of a VDH_EAOP structure, or NULL.
 
 
 
 
 
=== VDHOpen Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). If the function fails, ''VDHGetError''should be called to determine the nature of the problem. ''VDHGetError''can return the following errors:
 
ERROR_DISK_FULL <br />ERROR_OPEN_FAILED <br />ERROR_FILE_NOT_FOUND <br />ERROR_INVALID_PARAMETER <br />ERROR_PATH_NOT_FOUND <br />ERROR_ACCESS_DENIED <br />ERROR_DRIVE_LOCKED <br />ERROR_NOT_DOS_DISK <br />ERROR_SHARING_BUFFER_EXCEEDED <br />ERROR_SHARING_VIOLATION <br />ERROR_INVALID_ACCESS <br />ERROR_CANNOT_MAKE <br />ERROR_TOO_MANY_OPEN_FILES <br />ERROR_NOT_ENOUGH_MEMORY
 
If the function is called at other than DOS session-task time, or if the ''pszFileName''pointer is invalid, a system halt occurs.
 
 
 
 
 
=== VDHOpen - Parameters ===
 
'''FileName'''(PSZ) Pointer to the ASCIIZ string containing the name of the device or file to open.
 
'''FileHandle'''(PHFILE) Where the system returns the file handle.
 
'''ActionTaken'''(PULONG) Where the system returns a description of the action taken as a result of this function call.
 
'''FileSize'''(ULONG) The new file's logical size (EOD) in bytes.
 
'''FileAttribute'''(ULONG) File attribute bits used on file creation.
 
'''OpenFLag'''(ULONG) Specifies the action taken depending on whether the file exists.
 
Possible actions are:
 
VDHOPEN_FILE_EXISTED File existed <br />VDHOPEN_FILE_CREATED File created <br />VDHOPEN_FILE_TRUNCATED File replaced
 
'''OpenMode'''(ULONG) Describes the mode of the ''Open''function.
 
'''EABuf'''(PVDH_EOAP) Address of a VDH_EAOP structure, or NULL.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). If the function fails, ''VDHGetError''should be called to determine the nature of the problem. ''VDHGetError''can return the following errors:
 
ERROR_DISK_FULL <br />ERROR_OPEN_FAILED <br />ERROR_FILE_NOT_FOUND <br />ERROR_INVALID_PARAMETER <br />ERROR_PATH_NOT_FOUND <br />ERROR_ACCESS_DENIED <br />ERROR_DRIVE_LOCKED <br />ERROR_NOT_DOS_DISK <br />ERROR_SHARING_BUFFER_EXCEEDED <br />ERROR_SHARING_VIOLATION <br />ERROR_INVALID_ACCESS <br />ERROR_CANNOT_MAKE <br />ERROR_TOO_MANY_OPEN_FILES <br />ERROR_NOT_ENOUGH_MEMORY
 
If the function is called at other than DOS session-task time, or if the ''pszFileName''pointer is invalid, a system halt occurs.
 
 
 
 
 
=== VDHOpen - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: Any handles the virtual device driver opened for the terminating DOS session must be closed with ''VDHClose''.
 
Notes: Using ''VDHOpen''does not interfere with the handle space available to the DOS session with INT 21H, except that it does count against the system- wide limit on the number of open file handles. These ''VDHOpen''handles and the handles returned from INT 21H $Open cannot be used interchangeably.
 
 
 
 
 
=== VDHOpen - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHOpenPDD ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function gets the address of the routine in a physical device driver that the virtual device driver uses to communicate with the physical device driver. The physical device driver's device must have previously registered its name and entry point using the DevHlp service ''RegisterPDD''.
 
<pre class="western">#include mvdm.h
 
PSZ        DeviceName;    /*  Pointer to device name of physical device driver to open */
FPFNVDD    VDDEntryPoint;  /*  VDD entry point for VDD/PDD communication */
FPFNPDD    rc;
 
rc = VDHOpenPDD(DeviceName, VDDEntryPoint);</pre>
 
 
 
 
=== VDHOpenPDD - Format ===
 
This function gets the address of the routine in a physical device driver that the virtual device driver uses to communicate with the physical device driver. The physical device driver's device must have previously registered its name and entry point using the DevHlp service ''RegisterPDD''.
 
<pre class="western">#include mvdm.h
 
PSZ        DeviceName;    /*  Pointer to device name of physical device driver to open */
FPFNVDD    VDDEntryPoint;  /*  VDD entry point for VDD/PDD communication */
FPFNPDD    rc;
 
rc = VDHOpenPDD(DeviceName, VDDEntryPoint);</pre>
 
 
 
 
=== VDHOpenPDD Parameter - DeviceName ===
 
'''DeviceName'''(PSZ) Pointer to the device name of the physical device driver to open.
 
 
 
 
 
=== VDHOpenPDD Parameter - VDDEntryPoint ===
 
'''VDDEntryPoint'''(FPFNVDD) Virtual device driver entry point for use by the physical device driver. Since physical device drivers are 16:16 modules, this is a 16:32 entry point.
 
The interface for the ''VDDEntryPoint'':
 
<pre class="western"> USHORT VDDENTRY VDDEntryPoint (ulFunc, ul1, ul2)
 
ENTRY
    ULONG ulFunc - function code
          All function codes are private to a physical device driver/
          virtual device driver pair.
    ULONG ul1 - function/specific;
          If a pointer, it is 16:16, and will generally be an input packet
    ULONG ul2 - function/specific;
          If a pointer, it is 16:16, and will generally be an output packet
EXIT-SUCCESS  Returns !0
EXIT-FAILURE  Returns 0</pre>
 
 
 
 
 
 
=== VDHOpenPDD Return Value - rc ===
 
'''rc'''(FPFNPDD) - returns
 
Success If the function is successful, it returns a pointer to the physical device driver Inter-Device-Driver Communication (IDC) function. See &quot; RegisterPDD&quot; in the ''OS/2 Physical Device Driver Reference''for a description of the physical device driver's IDC function.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHOpenPDD - Parameters ===
 
'''DeviceName'''(PSZ) Pointer to the device name of the physical device driver to open.
 
'''VDDEntryPoint'''(FPFNVDD) Virtual device driver entry point for use by the physical device driver. Since physical device drivers are 16:16 modules, this is a 16:32 entry point.
 
The interface for the ''VDDEntryPoint'':
 
<pre class="western"> USHORT VDDENTRY VDDEntryPoint (ulFunc, ul1, ul2)
 
ENTRY
    ULONG ulFunc - function code
          All function codes are private to a physical device driver/
          virtual device driver pair.
    ULONG ul1 - function/specific;
          If a pointer, it is 16:16, and will generally be an input packet
    ULONG ul2 - function/specific;
          If a pointer, it is 16:16, and will generally be an output packet
EXIT-SUCCESS  Returns !0
EXIT-FAILURE  Returns 0</pre>
 
 
'''rc'''(FPFNPDD) - returns
 
Success If the function is successful, it returns a pointer to the physical device driver Inter-Device-Driver Communication (IDC) function. See &quot; RegisterPDD&quot; in the ''OS/2 Physical Device Driver Reference''for a description of the physical device driver's IDC function.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHOpenPDD - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Session Terminations: The virtual device driver must communicate with the physical device driver to ensure that any resources the physical device driver has for the terminating DOS session are freed.
 
 
 
 
 
=== VDHOpenPDD - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHOpenVDD ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns a handle to a virtual device driver that can be used with ''VDHRequestVDD''to enable a virtual device driver to communicate with another virtual device driver. The name must be one that was previously registered by using ''VDHRegisterVDD''.
 
<pre class="western">#include mvdm.h
 
PSZ    VDDName;  /*  Pointer to the name of the virtual device driver to open */
HVDD    rc;
 
rc = VDHOpenVDD(VDDName);</pre>
 
 
 
 
=== VDHOpenVDD - Format ===
 
This function returns a handle to a virtual device driver that can be used with ''VDHRequestVDD''to enable a virtual device driver to communicate with another virtual device driver. The name must be one that was previously registered by using ''VDHRegisterVDD''.
 
<pre class="western">#include mvdm.h
 
PSZ    VDDName;  /*  Pointer to the name of the virtual device driver to open */
HVDD    rc;
 
rc = VDHOpenVDD(VDDName);</pre>
 
 
 
 
=== VDHOpenVDD Parameter - VDDName ===
 
'''VDDName'''(PSZ) Pointer to a string containing the name of the virtual device driver to open.
 
 
 
 
 
=== VDHOpenVDD Return Value - rc ===
 
'''rc'''(HVDD) - returns
 
Success If the function is successful, it returns a handle to the virtual device driver.
 
Failure If the function fails, it returns 0 (zero). This can occur if:
 
*The virtual device driver referenced by ''VDDName''is not found. <br />*The virtual device driver was found, but has not registered a worker function (the routine that gets control when this interface is called) for virtual device driver/virtual device driver communication.
 
If this function is called with invalid parameters or in the incorrect context, a system halt occurs.
 
 
 
 
 
=== VDHOpenVDD - Parameters ===
 
'''VDDName'''(PSZ) Pointer to a string containing the name of the virtual device driver to open.
 
'''rc'''(HVDD) - returns
 
Success If the function is successful, it returns a handle to the virtual device driver.
 
Failure If the function fails, it returns 0 (zero). This can occur if:
 
*The virtual device driver referenced by ''VDDName''is not found. <br />*The virtual device driver was found, but has not registered a worker function (the routine that gets control when this interface is called) for virtual device driver/virtual device driver communication.
 
If this function is called with invalid parameters or in the incorrect context, a system halt occurs.
 
 
 
 
 
=== VDHOpenVDD - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context, typically during DOS session creation.
 
DOS Session Terminations: The virtual device driver must communicate with the opened virtual device driver to ensure that any resources for the terminating DOS session are freed. In addition, the virtual device driver must communicate with any virtual device driver or OS/2 clients to ensure that any resources created due to the connection are freed. Notes: The recommended way for two virtual device drivers to rendezvous with this function is for each to attempt to open the other at the first creation of a DOS session. This allows the two virtual device drivers to work together regardless of the order in which they are initialized.
 
 
 
 
 
=== VDHOpenVDD - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHOpenVIRQ ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns an IRQ handle for use with the other Virtual Programmable Interrupt Controller (VPIC) services and, optionally, sets handlers called when an End Of Interrupt (EOI) or Interrupt Return (IRET) is executed during a simulated interrupt.
 
<pre class="western">#include mvdm.h
 
IRQN    IRQNumber;    /*  Number of the IRQ to open */
PFN      EOIHandler;  /*  Address of End-Of-Interrupt (EOI) handler */
PFN      IRETHandler;  /*  Address of Interrupt Return (IRET) handler */
ULONG    Timeout;      /*  IRET timeout value in milliseconds */
ULONG    OptionFlag;  /*  Indicates whether the IRQ can be shared */
HIRQ    rc;
 
rc = VDHOpenVIRQ(IRQNumber, EOIHandler, IRETHandler,
      Timeout, OptionFlag);</pre>
 
 
 
 
=== VDHOpenVIRQ - Format ===
 
This function returns an IRQ handle for use with the other Virtual Programmable Interrupt Controller (VPIC) services and, optionally, sets handlers called when an End Of Interrupt (EOI) or Interrupt Return (IRET) is executed during a simulated interrupt.
 
<pre class="western">#include mvdm.h
 
IRQN    IRQNumber;    /*  Number of the IRQ to open */
PFN      EOIHandler;  /*  Address of End-Of-Interrupt (EOI) handler */
PFN      IRETHandler;  /*  Address of Interrupt Return (IRET) handler */
ULONG    Timeout;      /*  IRET timeout value in milliseconds */
ULONG    OptionFlag;  /*  Indicates whether the IRQ can be shared */
HIRQ    rc;
 
rc = VDHOpenVIRQ(IRQNumber, EOIHandler, IRETHandler,
      Timeout, OptionFlag);</pre>
 
 
 
 
=== VDHOpenVIRQ Parameter - IRQNumber ===
 
'''IRQNumber'''(IRQN) Number of the IRQ to open.
 
 
 
 
 
=== VDHOpenVIRQ Parameter - EOIHandler ===
 
'''EOIHandler'''(PFN) Address of End-Of-Interrupt (EOI) handler.
 
Linear address of the handler to be called when EOI is received by VPIC from a DOS session for the IRQ. If this is not desired, put a 0 (zero) in this parameter. Note that the IRQ is no longer &quot;in service&quot; (the ISR bit has been cleared) when the virtual device driver's EOI handler is called. The interface to the EOI handler is:
 
<pre class="western">VOID HOOKENTRY EOIHdlr(pcrf)
    ENTRY  pcrf - Pointer to client register frame
    EXIT    None
    USES    EAX, ECX, EDX, FS, GS, Flags
    CONTEXT DOS session-task</pre>
 
 
 
 
 
 
=== VDHOpenVIRQ Parameter - IRETHandler ===
 
'''IRETHandler'''(PFN) Address of Interrupt Return (IRET) handler.
 
Linear address of the handler to be called when the IRET in the DOS session 's interrupt code is executed for this IRQ. If this is not desired, set the parameter to 0 (zero). The interface for the IRET routine is:
 
<pre class="western">VOID HOOKENTRY IRETHdlr(pcrf)
    ENTRY  pcrf - Pointer to client register frame
    EXIT    None
    USES    EAX, ECX, EDX, FS, GS, Flags
    CONTEXT DOS session-task</pre>
 
 
 
 
 
 
=== VDHOpenVIRQ Parameter - Timeout ===
 
'''Timeout'''(ULONG) IRET timeout value in milliseconds. When the timeout expires, the virtual device driver's IRET handler is called as if the IRET had occurred. A value of -1 indicates that no timeout occurs.
 
 
 
 
 
=== VDHOpenVIRQ Parameter - OptionFlag ===
 
'''OptionFlag'''(ULONG) Option flag. Indicates whether the IRQ can be shared.
 
Possible value:
 
VPIC_SHARE_IRQ Indicates that the virtual device driver is willing to share the IRQ with another virtual device driver. All virtual device drivers that virtualize the same IRQ must pass this flag. Whether a particular IRQ is shared or unshared is determined by the setting of ''OptionFlag''by the first virtual device driver to open the IRQ.
 
 
 
 
 
=== VDHOpenVIRQ Return Value - rc ===
 
'''rc'''(HIRQ) - returns
 
Success If the function is successful, it returns an IRQ handle.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''IRQNumber'', ''EOIHandler'', ''IRETHandler'', or ''OptionFlag''are invalid, a system halt occurs.
 
 
 
 
 
=== VDHOpenVIRQ - Parameters ===
 
'''IRQNumber'''(IRQN) Number of the IRQ to open.
 
'''EOIHandler'''(PFN) Address of End-Of-Interrupt (EOI) handler.
 
Linear address of the handler to be called when EOI is received by VPIC from a DOS session for the IRQ. If this is not desired, put a 0 (zero) in this parameter. Note that the IRQ is no longer &quot;in service&quot; (the ISR bit has been cleared) when the virtual device driver's EOI handler is called. The interface to the EOI handler is:
 
<pre class="western">VOID HOOKENTRY EOIHdlr(pcrf)
    ENTRY  pcrf - Pointer to client register frame
    EXIT    None
    USES    EAX, ECX, EDX, FS, GS, Flags
    CONTEXT DOS session-task</pre>
 
 
'''IRETHandler'''(PFN) Address of Interrupt Return (IRET) handler.
 
Linear address of the handler to be called when the IRET in the DOS session 's interrupt code is executed for this IRQ. If this is not desired, set the parameter to 0 (zero). The interface for the IRET routine is:
 
<pre class="western">VOID HOOKENTRY IRETHdlr(pcrf)
    ENTRY  pcrf - Pointer to client register frame
    EXIT    None
    USES    EAX, ECX, EDX, FS, GS, Flags
    CONTEXT DOS session-task</pre>
 
 
'''Timeout'''(ULONG) IRET timeout value in milliseconds. When the timeout expires, the virtual device driver's IRET handler is called as if the IRET had occurred. A value of -1 indicates that no timeout occurs.
 
'''OptionFlag'''(ULONG) Option flag. Indicates whether the IRQ can be shared.
 
Possible value:
 
VPIC_SHARE_IRQ Indicates that the virtual device driver is willing to share the IRQ with another virtual device driver. All virtual device drivers that virtualize the same IRQ must pass this flag. Whether a particular IRQ is shared or unshared is determined by the setting of ''OptionFlag''by the first virtual device driver to open the IRQ.
 
'''rc'''(HIRQ) - returns
 
Success If the function is successful, it returns an IRQ handle.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''IRQNumber'', ''EOIHandler'', ''IRETHandler'', or ''OptionFlag''are invalid, a system halt occurs.
 
 
 
 
 
=== VDHOpenVIRQ - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: A maximum of 32 virtual device drivers can share an IRQ.
 
 
 
 
 
=== VDHOpenVIRQ - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPhysicalDisk ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns information about partitionable disks.
 
<pre class="western">#include mvdm.h
 
ULONG    Function;  /*  Type of partitionable disks' information */
PULONG    DataPtr;  /*  Pointer to the return buffer */
ULONG    DataLen;  /*  Length of the return buffer */
PULONG    ParmPtr;  /*  Pointer to the user-supplied information */
ULONG    ParmLen;  /*  Length of the user-supplied information */
BOOL      rc;
 
rc = VDHPhysicalDisk(Function, DataPtr, DataLen,
      ParmPtr, ParmLen);</pre>
 
 
 
 
=== VDHPhysicalDisk - Format ===
 
This function returns information about partitionable disks.
 
<pre class="western">#include mvdm.h
 
ULONG    Function;  /*  Type of partitionable disks' information */
PULONG    DataPtr;  /*  Pointer to the return buffer */
ULONG    DataLen;  /*  Length of the return buffer */
PULONG    ParmPtr;  /*  Pointer to the user-supplied information */
ULONG    ParmLen;  /*  Length of the user-supplied information */
BOOL      rc;
 
rc = VDHPhysicalDisk(Function, DataPtr, DataLen,
      ParmPtr, ParmLen);</pre>
 
 
 
 
=== VDHPhysicalDisk Parameter - Function ===
 
'''Function'''(ULONG) Type of partitionable disks' information to obtain.
 
Possible values are:
 
VDHPHYD_GET_DISKS Obtain the total number of partitionable disks <br />VDHPHYD_GET_HANDLE Obtain a handle to use with the Category 9 IOCtls <br />VDHPHYD_RELEASE_HANDLE Release a handle for a partitionable disk
 
 
 
 
 
=== VDHPhysicalDisk Parameter - DataPtr ===
 
'''DataPtr'''(PULONG) Pointer to the return buffer.
 
 
 
 
 
=== VDHPhysicalDisk Parameter - DataLen ===
 
'''DataLen'''(ULONG) Length of the return buffer.
 
The returned data for each function is described as follows (all lengths are in bytes):
 
VDHPHYD_GET_DISKS Data Length=2. Total number of partitionable disks in the system. 1-based.
 
VDHPHYD_GET_HANDLE Data Length=2. Handle for the specified partitionable disk for Category 9 IOCtls.
 
VDHPHYD_RELEASE_HANDLE Data Length=0. None; pointer must be 0 (zero).
 
 
 
 
 
=== VDHPhysicalDisk Parameter - ParmPtr ===
 
'''ParmPtr'''(PULONG) Pointer to the user-supplied information.
 
 
 
 
 
=== VDHPhysicalDisk Parameter - ParmLen ===
 
'''ParmLen'''(ULONG) Length of the user-supplied information (all lengths are in bytes):
 
VDHPHYD_GET_DISKS Parm Length=0. None; must be set to 0 (zero). 1-based.
 
VDHPHYD_GET_HANDLE Parm Length=string length. ASCIIZ string that specifies the partitionable disk.
 
VDHPHYD_RELEASE_HANDLE Parm Length=2. Handle obtained from VDHPHYD_GET_ HANDLE.
 
 
 
 
 
=== VDHPhysicalDisk Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. ''VDHGetError''can return the following error codes:
 
ERROR_ACCESS_DENIED <br />ERROR_INVALID_FUNCTION <br />ERROR_INVALID_HANDLE <br />ERROR_INVALID_PARAMETER <br />ERROR_LOCK_VIOLATION
 
If ''VDHPhysicalDisk''is called in any context except DOS session task time, a system halt occurs.
 
 
 
 
 
=== VDHPhysicalDisk - Parameters ===
 
'''Function'''(ULONG) Type of partitionable disks' information to obtain.
 
Possible values are:
 
VDHPHYD_GET_DISKS Obtain the total number of partitionable disks <br />VDHPHYD_GET_HANDLE Obtain a handle to use with the Category 9 IOCtls <br />VDHPHYD_RELEASE_HANDLE Release a handle for a partitionable disk
 
'''DataPtr'''(PULONG) Pointer to the return buffer.
 
'''DataLen'''(ULONG) Length of the return buffer.
 
The returned data for each function is described as follows (all lengths are in bytes):
 
VDHPHYD_GET_DISKS Data Length=2. Total number of partitionable disks in the system. 1-based.
 
VDHPHYD_GET_HANDLE Data Length=2. Handle for the specified partitionable disk for Category 9 IOCtls.
 
VDHPHYD_RELEASE_HANDLE Data Length=0. None; pointer must be 0 (zero).
 
'''ParmPtr'''(PULONG) Pointer to the user-supplied information.
 
'''ParmLen'''(ULONG) Length of the user-supplied information (all lengths are in bytes):
 
VDHPHYD_GET_DISKS Parm Length=0. None; must be set to 0 (zero). 1-based.
 
VDHPHYD_GET_HANDLE Parm Length=string length. ASCIIZ string that specifies the partitionable disk.
 
VDHPHYD_RELEASE_HANDLE Parm Length=2. Handle obtained from VDHPHYD_GET_ HANDLE.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. ''VDHGetError''can return the following error codes:
 
ERROR_ACCESS_DENIED <br />ERROR_INVALID_FUNCTION <br />ERROR_INVALID_HANDLE <br />ERROR_INVALID_PARAMETER <br />ERROR_LOCK_VIOLATION
 
If ''VDHPhysicalDisk''is called in any context except DOS session task time, a system halt occurs.
 
 
 
 
 
=== VDHPhysicalDisk - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: The handle obtained with Function Value=2 is released with Function Value=3. The ASCIIZ string used to specify the partitionable disk must be of the following format:
 
<pre class="western">    number:&lt;null byte&gt;
 
    Where:
          number      Specifies the partitionable disk (1-based) number in ASCII
          :            Must be present
          &lt;null byte&gt;  Specifies the byte of 0 for the ASCIIZ string</pre>
Notes: If the pointers passed by this function are allocated from the stack , then the ''SSToDS''macro must be used to make the DS pointer relative. Addresses (pointers) inside device-specific data and parameter packets are not translated.
 
 
 
 
 
=== VDHPhysicalDisk - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPopInt ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function reverses the effects of ''VDHPushInt''. It removes the Interrupt Return (IRET) frame from the client's stack and restores the client's CS:IP to what was in the IRET frame.
 
<pre class="western">#include mvdm.h
 
VOID    ;
BOOL    rc;
 
rc = VDHPopInt();</pre>
 
 
 
 
=== VDHPopInt - Format ===
 
This function reverses the effects of ''VDHPushInt''. It removes the Interrupt Return (IRET) frame from the client's stack and restores the client's CS:IP to what was in the IRET frame.
 
<pre class="western">#include mvdm.h
 
VOID    ;
BOOL    rc;
 
rc = VDHPopInt();</pre>
 
 
 
 
=== VDHPopInt Parameter - ===
 
None.
 
 
 
 
 
=== VDHPopInt Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack overflow would occur. A stack exception will be simulated to the client.
 
 
 
 
 
=== VDHPopInt - Parameters ===
 
None.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack overflow would occur. A stack exception will be simulated to the client.
 
 
 
 
 
=== VDHPopInt - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This function always returns Successful when the DOS session is in client mode because no data accesses below 1MB can cause a fault.
 
 
 
 
 
=== VDHPopInt - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPopRegs ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function reverses the ''VDHPushRegs''by popping the specified client registers into the Client Register Frame (CRF) from the client's stack.
 
<pre class="western">#include mvdm.h
 
FLAGS    RegFlag;  /*  Indicates which client registers to pop */
BOOL    rc;
 
rc = VDHPopRegs(RegFlag);</pre>
 
 
 
 
=== VDHPopRegs - Format ===
 
This function reverses the ''VDHPushRegs''by popping the specified client registers into the Client Register Frame (CRF) from the client's stack.
 
<pre class="western">#include mvdm.h
 
FLAGS    RegFlag;  /*  Indicates which client registers to pop */
BOOL    rc;
 
rc = VDHPopRegs(RegFlag);</pre>
 
 
 
 
=== VDHPopRegs Parameter - RegFlag ===
 
'''RegFlag'''(FLAGS) Flag indicating which client registers to pop.
 
These flags can be &quot;ORed&quot; together to indicate more than one register. Possible values are:
 
VDHREG_AX Pop the AX register <br />VDHREG_BX Pop the BX register <br />VDHREG_CX Pop the CX register <br />VDHREG_DX Pop the DX register <br />VDHREG_SI Pop the SI register <br />VDHREG_DI Pop the DI register <br />VDHREG_BP Pop the BP register <br />VDHREG_SP Pop the SP register <br />VDHREG_DS Pop the DS register <br />VDHREG_ES Pop the ES register <br />VDHREG_SS Pop the SS register <br />VDHREG_FLAG Pop the Flags register <br />VDHREG_ALL Pop all the registers <br />VDHREG_GENERAL Pop all the registers except SS and SP
 
 
 
 
 
=== VDHPopRegs Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If this function fails, it returns 0 (zero) if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception is simulated to the client. If ''RegFlag''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHPopRegs - Parameters ===
 
'''RegFlag'''(FLAGS) Flag indicating which client registers to pop.
 
These flags can be &quot;ORed&quot; together to indicate more than one register. Possible values are:
 
VDHREG_AX Pop the AX register <br />VDHREG_BX Pop the BX register <br />VDHREG_CX Pop the CX register <br />VDHREG_DX Pop the DX register <br />VDHREG_SI Pop the SI register <br />VDHREG_DI Pop the DI register <br />VDHREG_BP Pop the BP register <br />VDHREG_SP Pop the SP register <br />VDHREG_DS Pop the DS register <br />VDHREG_ES Pop the ES register <br />VDHREG_SS Pop the SS register <br />VDHREG_FLAG Pop the Flags register <br />VDHREG_ALL Pop all the registers <br />VDHREG_GENERAL Pop all the registers except SS and SP
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If this function fails, it returns 0 (zero) if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception is simulated to the client. If ''RegFlag''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHPopRegs - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: The caller should be careful to pass the same ''RegFlag''value to ''VDHPopRegs''that was used for the corresponding ''VDHPushRegs''call. If the caller does not do this, the client stack can become damaged. This function always returns Successful when ''RegFlag''is valid and the DOS session is in V86 mode because no data accesses below 1MB can cause a fault.
 
 
 
 
 
=== VDHPopRegs - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPopStack ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function pops the data off the client's stack.
 
<pre class="western">#include mvdm.h
 
ULONG    NumBytes;  /*  Number of bytes to pop off the client's stack */
PVOID    DataPtr;  /*  Pointer to data to pop off client's stack */
BOOL    rc;
 
rc = VDHPopStack(NumBytes, DataPtr);</pre>
 
 
 
 
=== VDHPopStack - Format ===
 
This function pops the data off the client's stack.
 
<pre class="western">#include mvdm.h
 
ULONG    NumBytes;  /*  Number of bytes to pop off the client's stack */
PVOID    DataPtr;  /*  Pointer to data to pop off client's stack */
BOOL    rc;
 
rc = VDHPopStack(NumBytes, DataPtr);</pre>
 
 
 
 
=== VDHPopStack Parameter - NumBytes ===
 
'''NumBytes'''(ULONG) Number of bytes to pop off the client's stack. Must be an even number.
 
 
 
 
 
=== VDHPopStack Parameter - DataPtr ===
 
'''DataPtr'''(PVOID) Pointer to the data to pop off the client's stack.
 
 
 
 
 
=== VDHPopStack Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If this function fails, it returns 0 (zero) if a fault would occur when accessing the user stack. If ''NumBytes''is odd, a system halt occurs.
 
 
 
 
 
=== VDHPopStack - Parameters ===
 
'''NumBytes'''(ULONG) Number of bytes to pop off the client's stack. Must be an even number.
 
'''DataPtr'''(PVOID) Pointer to the data to pop off the client's stack.
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If this function fails, it returns 0 (zero) if a fault would occur when accessing the user stack. If ''NumBytes''is odd, a system halt occurs.
 
 
 
 
 
=== VDHPopStack - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This is a very low-level service. Appropriate care should be exercised in its use to ensure that the client's stack is not damaged. This service handles stack wraparound, and always returns successful when the DOS session is in V86-mode because no data accesses below 1MB can cause a fault.
 
 
 
 
 
=== VDHPopStack - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPopup ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function displays a message according to the Message ID, and gets a response from the user.
 
<pre class="western">#include mvdm.h
 
PSZ      ParmTable;    /*  Pointer to a table of substitution strings */
ULONG    StrCount;    /*  Number of substitution strings */
ULONG    MsgNumber;    /*  Message number */
PULONG    RespPtr;      /*  Pointer to a DD to receive the response */
ULONG    RespAllowed;  /*  Bit field describing the allowed responses */
PVOID    Reserved;    /*  Reserved; must be set to NULL */
BOOL      rc;
 
rc = VDHPopup(ParmTable, StrCount, MsgNumber,
      RespPtr, RespAllowed, Reserved);</pre>
 
 
 
 
=== VDHPopup - Format ===
 
This function displays a message according to the Message ID, and gets a response from the user.
 
<pre class="western">#include mvdm.h
 
PSZ      ParmTable;    /*  Pointer to a table of substitution strings */
ULONG    StrCount;    /*  Number of substitution strings */
ULONG    MsgNumber;    /*  Message number */
PULONG    RespPtr;      /*  Pointer to a DD to receive the response */
ULONG    RespAllowed;  /*  Bit field describing the allowed responses */
PVOID    Reserved;    /*  Reserved; must be set to NULL */
BOOL      rc;
 
rc = VDHPopup(ParmTable, StrCount, MsgNumber,
      RespPtr, RespAllowed, Reserved);</pre>
 
 
 
 
=== VDHPopup Parameter - ParmTable ===
 
'''ParmTable'''(PSZ) Pointer to a table of substitution strings.
 
 
 
 
 
=== VDHPopup Parameter - StrCount ===
 
'''StrCount'''(ULONG) Number of substitution strings.
 
 
 
 
 
=== VDHPopup Parameter - MsgNumber ===
 
'''MsgNumber'''(ULONG) Message number.
 
 
 
 
 
=== VDHPopup Parameter - RespPtr ===
 
'''RespPtr'''(PULONG) Pointer to a DD to receive the returned response, filled on exit.
 
 
 
 
 
=== VDHPopup Parameter - RespAllowed ===
 
'''RespAllowed'''(ULONG) Bit field describing the allowed responses.
 
The allowed values are (any combination of these flags can be specified):
 
VDHP_FAIL (0001H) <br />VDHP_RETRY (0004H) <br />VDHP_IGNORE (0008H) <br />VDHP_TERMINATE_SESSION (0002H)
 
 
 
 
 
=== VDHPopup Parameter - Reserved ===
 
'''Reserved'''(PVOID) Reserved. Must be set to NULL.
 
 
 
 
 
=== VDHPopup Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value and the variable pointed to by ''RespPtr''is filled in with actual response selected by the user.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHPopup - Parameters ===
 
'''ParmTable'''(PSZ) Pointer to a table of substitution strings.
 
'''StrCount'''(ULONG) Number of substitution strings.
 
'''MsgNumber'''(ULONG) Message number.
 
'''RespPtr'''(PULONG) Pointer to a DD to receive the returned response, filled on exit.
 
'''RespAllowed'''(ULONG) Bit field describing the allowed responses.
 
The allowed values are (any combination of these flags can be specified):
 
VDHP_FAIL (0001H) <br />VDHP_RETRY (0004H) <br />VDHP_IGNORE (0008H) <br />VDHP_TERMINATE_SESSION (0002H)
 
'''Reserved'''(PVOID) Reserved. Must be set to NULL.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value and the variable pointed to by ''RespPtr''is filled in with actual response selected by the user.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHPopup - Purpose ===
 
Context Issues: This function can be called in the initialization context or the DOS session-task context. If it is called at initialization time, the message is displayed as a string on the console as if a ''DosWrite''to standard output (''stdout'') had been made. No prompt is displayed, and no user response is returned. ''ResponsePtr''is filled in with 0 (zero).
 
DOS Session Terminations: A DOS session cannot be terminated if it is waiting in this call for a user response.
 
Notes: This service is intended for virtual device drivers, which must inform the user of some extraordinary circumstance. For example, the virtual COM device driver (VCOM) issues this call to inform the user that a COM port is busy and gives the user a choice of how to handle the situation .
 
The input value of ''ResponsePtr''is not used. &quot;Retry&quot; is the default action chosen for hard errors. If Retry is not allowed, &quot;End the Program&quot; is chosen as the default.
 
 
 
 
 
=== VDHPopup - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPostEventSem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function posts an event semaphore. All the threads blocked on this semaphore will wake up.
 
<pre class="western">#include mvdm.h
 
HVDHSEM    EventSemHandle;  /*  Handle of an event semaphore */
 
VDHPostEventSem(EventSemHandle);</pre>
 
 
 
 
=== VDHPostEventSem - Format ===
 
This function posts an event semaphore. All the threads blocked on this semaphore will wake up.
 
<pre class="western">#include mvdm.h
 
HVDHSEM    EventSemHandle;  /*  Handle of an event semaphore */
 
VDHPostEventSem(EventSemHandle);</pre>
 
 
 
 
=== VDHPostEventSem Parameter - EventSemHandle ===
 
'''EventSemHandle'''(HVDHSEM) Handle of the event semaphore to post.
 
 
 
 
 
=== VDHPostEventSem - Return Value ===
 
Success If the function is successful, it will return nothing.
 
Failure Posting a semaphore that is invalid or is already posted causes a system halt to occur.
 
 
 
 
 
=== VDHPostEventSem - Parameters ===
 
'''EventSemHandle'''(HVDHSEM) Handle of the event semaphore to post.
 
Success If the function is successful, it will return nothing.
 
Failure Posting a semaphore that is invalid or is already posted causes a system halt to occur.
 
 
 
 
 
=== VDHPostEventSem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHPostEventSem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPrintClose ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is called by other virtual device drivers to flush and close a DOS session's open printers that have been opened for INT 17H printing. A DOS session can have more than one printer open. This service flushes and closes all of them.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  DOS session handle */
 
VDHPrintClose(VDMHandle);</pre>
 
 
 
 
=== VDHPrintClose - Format ===
 
This function is called by other virtual device drivers to flush and close a DOS session's open printers that have been opened for INT 17H printing. A DOS session can have more than one printer open. This service flushes and closes all of them.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  DOS session handle */
 
VDHPrintClose(VDMHandle);</pre>
 
 
 
 
=== VDHPrintClose Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) DOS session handle.
 
 
 
 
 
=== VDHPrintClose - Return Value ===
 
None.
 
 
 
 
 
=== VDHPrintClose - Parameters ===
 
'''VDMHandle'''(HVDM) DOS session handle.
 
None.
 
 
 
 
 
=== VDHPrintClose - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: The system will flush and close any open printers when the DOS session is terminated.
 
Notes: If a printer has been left open because of direct access to the parallel ports, it will also be closed.
 
 
 
 
 
=== VDHPrintClose - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPushFarCall ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function simulates a Far Call to V86 code as if a DOS program had executed a Far Call instruction.
 
<pre class="western">#include mvdm.h
 
FPFN    SegOffAddr;  /*  Address of V86 mode or protected mode code to call */
BOOL    rc;
 
rc = VDHPushFarCall(SegOffAddr);</pre>
 
 
 
 
=== VDHPushFarCall - Format ===
 
This function simulates a Far Call to V86 code as if a DOS program had executed a Far Call instruction.
 
<pre class="western">#include mvdm.h
 
FPFN    SegOffAddr;  /*  Address of V86 mode or protected mode code to call */
BOOL    rc;
 
rc = VDHPushFarCall(SegOffAddr);</pre>
 
 
 
 
=== VDHPushFarCall Parameter - SegOffAddr ===
 
'''SegOffAddr'''(FPFN) The V86-mode segment:offset address of the V86-mode code to call, or selector:offset of protected-mode code to call.
 
 
 
 
 
=== VDHPushFarCall Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception is simulated to the client.
 
 
 
 
 
=== VDHPushFarCall - Parameters ===
 
'''SegOffAddr'''(FPFN) The V86-mode segment:offset address of the V86-mode code to call, or selector:offset of protected-mode code to call.
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception is simulated to the client.
 
 
 
 
 
=== VDHPushFarCall - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This function does not take effect until the operating system returns to the DOS session. In most cases, ''VDHArmReturnHook''is called after this service. This allows the virtual device driver to regain control when the called V86 code executes its Far Return (RETF).
 
This function always returns successful when the DOS session is in V86 mode because no data accesses below 1MB can cause a fault.
 
 
 
 
 
=== VDHPushFarCall - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPushInt ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used to change the DOS session's control flow to the interrupt handler when an interrupt is simulated. This function also simulates an interrupt to a specified V86-interrupt vector as if a DOS program has executed an INT '''''n'''''instruction. Any virtual device driver hooked on this interrupt with ''VDHInstallIntHook''will get control as expected. The ''VDHArmReturnHook''service can be used after this function is called to regain control when the V86 code executes the Interrupt Return (IRET).
 
If the DOS session is in V86-mode, the V86-mode handler from the IVT is called. If the DOS session is in protected mode, the protected-mode interrupt handler is called.
 
<pre class="western">#include mvdm.h
 
ULONG    Vector;  /*  Number of the interrupt vector to push */
BOOL    rc;
 
rc = VDHPushInt(Vector);</pre>
 
 
 
 
=== VDHPushInt - Format ===
 
This function is used to change the DOS session's control flow to the interrupt handler when an interrupt is simulated. This function also simulates an interrupt to a specified V86-interrupt vector as if a DOS program has executed an INT '''''n'''''instruction. Any virtual device driver hooked on this interrupt with ''VDHInstallIntHook''will get control as expected. The ''VDHArmReturnHook''service can be used after this function is called to regain control when the V86 code executes the Interrupt Return (IRET).
 
If the DOS session is in V86-mode, the V86-mode handler from the IVT is called. If the DOS session is in protected mode, the protected-mode interrupt handler is called.
 
<pre class="western">#include mvdm.h
 
ULONG    Vector;  /*  Number of the interrupt vector to push */
BOOL    rc;
 
rc = VDHPushInt(Vector);</pre>
 
 
 
 
=== VDHPushInt Parameter - Vector ===
 
'''Vector'''(ULONG) Number of the interrupt vector to push (0-255).
 
 
 
 
 
=== VDHPushInt Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If ''Vector''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHPushInt - Parameters ===
 
'''Vector'''(ULONG) Number of the interrupt vector to push (0-255).
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If ''Vector''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHPushInt - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This function does not take effect until the operating system returns to V86 mode. This function always returns successful when the DOS session is in V86 mode because no data accesses below 1MB can cause a fault .
 
 
 
 
 
=== VDHPushInt - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPushRegs ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function pushes the specified client register from the Client Register Frame (CRF) to the client's stack. This service is usually used in conjunction with VDHPushFarCall to preserve user registers.
 
<pre class="western">#include mvdm.h
 
FLAGS    RegFlag;  /*  Flag indicating which client registers to push */
BOOL    rc;
 
rc = VDHPushRegs(RegFlag);</pre>
 
 
 
 
=== VDHPushRegs - Format ===
 
This function pushes the specified client register from the Client Register Frame (CRF) to the client's stack. This service is usually used in conjunction with VDHPushFarCall to preserve user registers.
 
<pre class="western">#include mvdm.h
 
FLAGS    RegFlag;  /*  Flag indicating which client registers to push */
BOOL    rc;
 
rc = VDHPushRegs(RegFlag);</pre>
 
 
 
 
=== VDHPushRegs Parameter - RegFlag ===
 
'''RegFlag'''(FLAGS) Flag indicating which client registers to push. These flags can be ORed together to indicate more than one register.
 
Possible values are:
 
VDHREG_AX Push the AX register <br />VDHREG_BX Push the BX register <br />VDHREG_CX Push the CX register <br />VDHREG_DX Push the DX register <br />VDHREG_SI Push the SI register <br />VDHREG_DI Push the DI register <br />VDHREG_BP Push the BP register <br />VDHREG_SP Push the SP register <br />VDHREG_DS Push the DS register <br />VDHREG_ES Push the ES register <br />VDHREG_SS Push the SS register <br />VDHREG_FLAG Push the Flags register <br />VDHREG_ALL Push all the registers <br />VDHREG_GENERAL Push all the registers except SS and SP
 
 
 
 
 
=== VDHPushRegs Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If ''RegFlag''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHPushRegs - Parameters ===
 
'''RegFlag'''(FLAGS) Flag indicating which client registers to push. These flags can be ORed together to indicate more than one register.
 
Possible values are:
 
VDHREG_AX Push the AX register <br />VDHREG_BX Push the BX register <br />VDHREG_CX Push the CX register <br />VDHREG_DX Push the DX register <br />VDHREG_SI Push the SI register <br />VDHREG_DI Push the DI register <br />VDHREG_BP Push the BP register <br />VDHREG_SP Push the SP register <br />VDHREG_DS Push the DS register <br />VDHREG_ES Push the ES register <br />VDHREG_SS Push the SS register <br />VDHREG_FLAG Push the Flags register <br />VDHREG_ALL Push all the registers <br />VDHREG_GENERAL Push all the registers except SS and SP
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If ''RegFlag''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHPushRegs - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Because the registers are saved on the DOS session stack (as opposed to a virtual device driver data structure), the virtual device driver is in no danger of losing track of data if the DOS session does not return to the virtual device driver. This service is used sparingly as it consumes DOS session stack space, and most DOS applications cannot tolerate excessive stack usage beyond their own needs.
 
This function always returns successful when ''RegFlag''is valid and the DOS session is in V86 mode because no data accessed below 1MB can cause a fault .
 
 
 
 
 
=== VDHPushRegs - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPushStack ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function pushes data onto the client's stack.
 
<pre class="western">#include mvdm.h
 
ULONG    NumBytes;  /*  Number of bytes to push on the client's stack */
PVOID    DataPtr;  /*  Pointer to the data to push on the stack */
BOOL    rc;
 
rc = VDHPushStack(NumBytes, DataPtr);</pre>
 
 
 
 
=== VDHPushStack - Format ===
 
This function pushes data onto the client's stack.
 
<pre class="western">#include mvdm.h
 
ULONG    NumBytes;  /*  Number of bytes to push on the client's stack */
PVOID    DataPtr;  /*  Pointer to the data to push on the stack */
BOOL    rc;
 
rc = VDHPushStack(NumBytes, DataPtr);</pre>
 
 
 
 
=== VDHPushStack Parameter - NumBytes ===
 
'''NumBytes'''(ULONG) Number of bytes to push onto the client's stack. Must be an even number.
 
 
 
 
 
=== VDHPushStack Parameter - DataPtr ===
 
'''DataPtr'''(PVOID) A pointer to the data to be pushed.
 
 
 
 
 
=== VDHPushStack Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If NumBytes is odd, a system halt occurs.
 
 
 
 
 
=== VDHPushStack - Parameters ===
 
'''NumBytes'''(ULONG) Number of bytes to push onto the client's stack. Must be an even number.
 
'''DataPtr'''(PVOID) A pointer to the data to be pushed.
 
'''rc'''(BOOL) - returns
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If NumBytes is odd, a system halt occurs.
 
 
 
 
 
=== VDHPushStack - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This is a very low-level service. Appropriate care should be exercised in its use to ensure that the client's stack is not corrupted. This service handles stack wraparound, and always returns successful when the DOS session is in V86-mode because no data accesses below 1MB can cause a fault.
 
 
 
 
 
=== VDHPushStack - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPutSysValue ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function sets a system value.
 
<pre class="western">#include mvdm.h
 
ULONG    Index;  /*  Index of the system variable to set */
ULONG    Value;  /*  New value for the system variable */
 
VDHPutSysValue(Index, Value);</pre>
 
 
 
 
=== VDHPutSysValue - Format ===
 
This function sets a system value.
 
<pre class="western">#include mvdm.h
 
ULONG    Index;  /*  Index of the system variable to set */
ULONG    Value;  /*  New value for the system variable */
 
VDHPutSysValue(Index, Value);</pre>
 
 
 
 
=== VDHPutSysValue Parameter - Index ===
 
'''Index'''(ULONG) Index of the system value to set. System value indexes are defined in VDMM.INC and listed in [[00822.htm|VDHQuerySysValue]].
 
 
 
 
 
=== VDHPutSysValue Parameter - Value ===
 
'''Value'''(ULONG) New value for the system variable.
 
 
 
 
 
=== VDHPutSysValue - Return Value ===
 
Success If the function was successful, it returns nothing.
 
Failure If Index is invalid, a system halt occurs.
 
 
 
 
 
=== VDHPutSysValue - Parameters ===
 
'''Index'''(ULONG) Index of the system value to set. System value indexes are defined in VDMM.INC and listed in [[00822.htm|VDHQuerySysValue]].
 
'''Value'''(ULONG) New value for the system variable.
 
Success If the function was successful, it returns nothing.
 
Failure If Index is invalid, a system halt occurs.
 
 
 
 
 
=== VDHPutSysValue - Purpose ===
 
Context Issues: This function can be called in the initialization or DOS session-task (DOS session creation) context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This service is intended for system virtual device drivers to export system constants, such as ROM memory size. The behavior of the system is undefined if this service is used for any other purpose.
 
 
 
 
 
=== VDHPutSysValue - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQueryFreePages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns the total amount of free virtual memory in bytes. This is the amount of memory that could be allocated successfully.
 
<pre class="western">#include mvdm.h
 
VOID    ;
ULONG    rc;
 
rc = VDHQueryFreePages();</pre>
 
 
 
 
=== VDHQueryFreePages - Format ===
 
This function returns the total amount of free virtual memory in bytes. This is the amount of memory that could be allocated successfully.
 
<pre class="western">#include mvdm.h
 
VOID    ;
ULONG    rc;
 
rc = VDHQueryFreePages();</pre>
 
 
 
 
=== VDHQueryFreePages Parameter - ===
 
None.
 
 
 
 
 
=== VDHQueryFreePages Return Value - rc ===
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the number of bytes of free virtual memory.
 
Failure If the function fails, it returns nothing.
 
 
 
 
 
=== VDHQueryFreePages - Parameters ===
 
None.
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the number of bytes of free virtual memory.
 
Failure If the function fails, it returns nothing.
 
 
 
 
 
=== VDHQueryFreePages - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This is a system-wide value that is not specific to the virtual address space of the DOS session.
 
 
 
 
 
=== VDHQueryFreePages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQueryHookData ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns a pointer to the reference data created during the call to VDHAllocHook.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle from VDHAllocHook */
PVOID    rc;
 
rc = VDHQueryHookData(HookHandle);</pre>
 
 
 
 
=== VDHQueryHookData - Format ===
 
This function returns a pointer to the reference data created during the call to VDHAllocHook.
 
<pre class="western">#include mvdm.h
 
HHOOK    HookHandle;  /*  Hook handle from VDHAllocHook */
PVOID    rc;
 
rc = VDHQueryHookData(HookHandle);</pre>
 
 
 
 
=== VDHQueryHookData Parameter - HookHandle ===
 
'''HookHandle'''(HHOOK) Hook handle (from VDHAllocHook) for the hook to query.
 
 
 
 
 
=== VDHQueryHookData Return Value - rc ===
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns a pointer to the reference data block.
 
Failure If HookHandle is invalid or if there is no reference data (that is, the RefDataSize parameter for VDHAllocHook is ''0''), a system halt occurs.
 
 
 
 
 
=== VDHQueryHookData - Parameters ===
 
'''HookHandle'''(HHOOK) Hook handle (from VDHAllocHook) for the hook to query.
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns a pointer to the reference data block.
 
Failure If HookHandle is invalid or if there is no reference data (that is, the RefDataSize parameter for VDHAllocHook is ''0''), a system halt occurs.
 
 
 
 
 
=== VDHQueryHookData - Purpose ===
 
Context Issues: This function can be called in the initialization, task, or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHQueryHookData - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQueryLin ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function converts a 16:16 (Far16) address to a 0:32 address. The 16:16 address can be a LDT-based or GDT-based address. The function is also callable on stack-based addresses.
 
<pre class="western">#include mvdm.h
 
F16PVOID    Far16Addr;  /*  16:16 addressto be converted */
PVOID      rc;
 
rc = VDHQueryLin(Far16Addr);</pre>
 
 
 
 
=== VDHQueryLin - Format ===
 
This function converts a 16:16 (Far16) address to a 0:32 address. The 16:16 address can be a LDT-based or GDT-based address. The function is also callable on stack-based addresses.
 
<pre class="western">#include mvdm.h
 
F16PVOID    Far16Addr;  /*  16:16 addressto be converted */
PVOID      rc;
 
rc = VDHQueryLin(Far16Addr);</pre>
 
 
 
 
=== VDHQueryLin Parameter - Far16Addr ===
 
'''Far16Addr'''(F16PVOID) The 16:16 address to be converted to a 0:32 address.
 
 
 
 
 
=== VDHQueryLin Return Value - rc ===
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the 0:32 address that corresponds to Far16Addr.
 
Failure If Far16Addr is an invalid selector, a system halt occurs.
 
 
 
 
 
=== VDHQueryLin - Parameters ===
 
'''Far16Addr'''(F16PVOID) The 16:16 address to be converted to a 0:32 address.
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns the 0:32 address that corresponds to Far16Addr.
 
Failure If Far16Addr is an invalid selector, a system halt occurs.
 
 
 
 
 
=== VDHQueryLin - Purpose ===
 
Context Issues: This function can be called in the initialization, task, or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This service does minimal checking on Far16Addr. The caller should make sure that Far16Addr is not invalid. If an invalid address is passed, this service can return an invalid address.
 
 
 
 
 
=== VDHQueryLin - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQueryKeyShift ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is called by the virtual mouse device driver to query the keyboard shift state of a DOS session.
 
<pre class="western">#include mvdm.h
 
HVDM      VDMHandle;  /*  DOS session handle */
USHORT    rc;
 
rc = VDHQueryKeyShift(VDMHandle);</pre>
 
 
 
 
=== VDHQueryKeyShift - Format ===
 
This function is called by the virtual mouse device driver to query the keyboard shift state of a DOS session.
 
<pre class="western">#include mvdm.h
 
HVDM      VDMHandle;  /*  DOS session handle */
USHORT    rc;
 
rc = VDHQueryKeyShift(VDMHandle);</pre>
 
 
 
 
=== VDHQueryKeyShift Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) DOS session handle.
 
 
 
 
 
=== VDHQueryKeyShift Return Value - rc ===
 
'''rc'''(USHORT) - returns Returns a USHORT which is a bitmask that indicates the current key state:
 
Right Shift 1 <br />Left Shift 2 <br />Ctrl 4 <br />ALT 8 <br />Left Ctrl 100 <br />Left ALT 200 <br />Right Ctrl 400 <br />Right ALT 800
 
 
 
 
 
=== VDHQueryKeyShift - Parameters ===
 
'''VDMHandle'''(HVDM) DOS session handle.
 
'''rc'''(USHORT) - returns Returns a USHORT which is a bitmask that indicates the current key state:
 
Right Shift 1 <br />Left Shift 2 <br />Ctrl 4 <br />ALT 8 <br />Left Ctrl 100 <br />Left ALT 200 <br />Right Ctrl 400 <br />Right ALT 800
 
 
 
 
 
=== VDHQueryKeyShift - Purpose ===
 
Context Issues: This function can be called only in the interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHQueryKeyShift - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQueryProperty ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns the current value of the specified DOS Setting.
 
<pre class="western">#include mvdm.h
 
PSZ      PropertyName;  /*  Pointer to a property name */
ULONG    rc;
 
rc = VDHQueryProperty(PropertyName);</pre>
 
 
 
 
=== VDHQueryProperty - Format ===
 
This function returns the current value of the specified DOS Setting.
 
<pre class="western">#include mvdm.h
 
PSZ      PropertyName;  /*  Pointer to a property name */
ULONG    rc;
 
rc = VDHQueryProperty(PropertyName);</pre>
 
 
 
 
=== VDHQueryProperty Parameter - PropertyName ===
 
'''PropertyName'''(PSZ) Pointer to an ASCIIZ string containing the property name for which information is being sought. Maximum length is 40 characters, including the terminating NULL.
 
 
 
 
 
=== VDHQueryProperty Return Value - rc ===
 
'''rc'''(ULONG) - returns
 
Success The format of the return value for successful depends on the type of the property being queried:
 
VDMP_BOOL The return value is a BOOL (Boolean). A ''0''value represents FALSE and a nonzero value represents TRUE.
 
VDMP_INT The return value is a DD. It is guaranteed to be valid with respect to the bounding information specified in VDHRegisterVDD. Only the low half (DW) of the DD is significant. The high half is always ''0''.
 
VDMP_ENUM The return value is a pointer to a NULL-terminated string. The string is guaranteed to be one of those specified in VDHRegisterVDD.
 
VDMP_STRING The return value is a pointer to a NULL-terminated string. The string is guaranteed to be, at most, as long as the limit specified in VDHRegisterVDD.
 
VDMP_MLSTR The return value is a pointer to a NULL-terminated string. The string is guaranteed to be, at most, as long as the limit specified in VDHRegisterVDD.
 
'''Note:'''For property types VDMP_ENUM, VDMP_STRING, and VDMP_MLSTR, a pointer to the current value is returned to the virtual device driver, thereby avoiding a condition where an OS/2 process might be trying to change the same value. The virtual device driver calls VDHFreeMem to free the string after the virtual device driver is finished with it.
 
Failure If the function fails, it returns NULL for property types VDMP_ENUM , VDMP_STRING, and VDMP_MLSTR, if there is insufficient memory to create a copy of the string value. In this case, the virtual device driver uses the default property value. NULL is also returned if pszName is invalid or is not a registered virtual device driver name.
 
 
 
 
 
=== VDHQueryProperty - Parameters ===
 
'''PropertyName'''(PSZ) Pointer to an ASCIIZ string containing the property name for which information is being sought. Maximum length is 40 characters, including the terminating NULL.
 
'''rc'''(ULONG) - returns
 
Success The format of the return value for successful depends on the type of the property being queried:
 
VDMP_BOOL The return value is a BOOL (Boolean). A ''0''value represents FALSE and a nonzero value represents TRUE.
 
VDMP_INT The return value is a DD. It is guaranteed to be valid with respect to the bounding information specified in VDHRegisterVDD. Only the low half (DW) of the DD is significant. The high half is always ''0''.
 
VDMP_ENUM The return value is a pointer to a NULL-terminated string. The string is guaranteed to be one of those specified in VDHRegisterVDD.
 
VDMP_STRING The return value is a pointer to a NULL-terminated string. The string is guaranteed to be, at most, as long as the limit specified in VDHRegisterVDD.
 
VDMP_MLSTR The return value is a pointer to a NULL-terminated string. The string is guaranteed to be, at most, as long as the limit specified in VDHRegisterVDD.
 
'''Note:'''For property types VDMP_ENUM, VDMP_STRING, and VDMP_MLSTR, a pointer to the current value is returned to the virtual device driver, thereby avoiding a condition where an OS/2 process might be trying to change the same value. The virtual device driver calls VDHFreeMem to free the string after the virtual device driver is finished with it.
 
Failure If the function fails, it returns NULL for property types VDMP_ENUM , VDMP_STRING, and VDMP_MLSTR, if there is insufficient memory to create a copy of the string value. In this case, the virtual device driver uses the default property value. NULL is also returned if pszName is invalid or is not a registered virtual device driver name.
 
 
 
 
 
=== VDHQueryProperty - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: All memory allocated by a virtual device driver for use by the terminating DOS session is freed by using VDHFreeMem.
 
Notes: A virtual device driver can assume that the property value is valid. The system validates all types, except VDMP_STRING and VDMP_MLSTR, by using the validation values passed on the call to VDHRegisterProperty. The string types are validated by calling the virtual device driver function registered through VDHRegisterProperty.
 
 
 
 
 
=== VDHQueryProperty - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQuerySel ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns the selector part of a 16:16 far pointer from a flat 0:32 address. The selector is in the Global Descriptor Table (GDT).
 
<pre class="western">#include mvdm.h
 
PVOID    VirtAddress;  /*  0:32 virtual address */
SEL      rc;
 
rc = VDHQuerySel(VirtAddress);</pre>
 
 
 
 
=== VDHQuerySel - Format ===
 
This function returns the selector part of a 16:16 far pointer from a flat 0:32 address. The selector is in the Global Descriptor Table (GDT).
 
<pre class="western">#include mvdm.h
 
PVOID    VirtAddress;  /*  0:32 virtual address */
SEL      rc;
 
rc = VDHQuerySel(VirtAddress);</pre>
 
 
 
 
=== VDHQuerySel Parameter - VirtAddress ===
 
'''VirtAddress'''(PVOID) A 0:32 virtual address.
 
 
 
 
 
=== VDHQuerySel Return Value - rc ===
 
'''rc'''(SEL) - returns
 
Success If the function is successful, it returns a nonzero selector.
 
Failure If the specified linear address is not in a virtual device driver data object, a system halt occurs.
 
 
 
 
 
=== VDHQuerySel - Parameters ===
 
'''VirtAddress'''(PVOID) A 0:32 virtual address.
 
'''rc'''(SEL) - returns
 
Success If the function is successful, it returns a nonzero selector.
 
Failure If the specified linear address is not in a virtual device driver data object, a system halt occurs.
 
 
 
 
 
=== VDHQuerySel - Purpose ===
 
Context Issues: This function can be called in the initialization and task context:
 
*During initialization time; query is allowed only on initialization and global data. <br />*Global, instance, and stack data are allowed during task time (typically DOS session creation time), but initialization data is not.
 
DOS Session Terminations: Selectors for virtual device driver instance data are destroyed when the DOS session terminates. The virtual device driver must ensure that any physical device driver that was given this kind of selector is finished with it.
 
Notes: This function works only on 0:32 addresses in virtual device driver data objects and stacks. Each virtual device driver data object is limited to a maximum of 64KB in size so that the following formula can be used. A virtual device driver that needs more than 64KB of a particular class (INIT , global, or instance) must use multiple objects.
 
Notice that the selectors for virtual device driver data are created to map starting at a 64KB linear address boundary. As a result, ''VDHQuerySel''needs to be called only once. The returned selector is valid for any memory in the particular object that contains the passed address, because the DOS Session Manager does not allow a virtual device driver data object to span a 64KB linear address boundary.
 
For virtual device driver instance data, this function returns a different GDT selector for each DOS session, and it can be called only in the context of a DOS session.
 
 
 
 
 
=== VDHQuerySel - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQuerySem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function queries the state of an event or mutex semaphore.
 
<pre class="western">#include mvdm.h
 
HVDHSEM        SemHandle;    /*  Handle to an event or mutex semaphore */
PVDHSEMSTATE    SemStatePtr;  /*  Pointer to a VDHSEMSTATE data area */
 
VDHQuerySem(SemHandle, SemStatePtr);</pre>
 
 
 
 
=== VDHQuerySem - Format ===
 
This function queries the state of an event or mutex semaphore.
 
<pre class="western">#include mvdm.h
 
HVDHSEM        SemHandle;    /*  Handle to an event or mutex semaphore */
PVDHSEMSTATE    SemStatePtr;  /*  Pointer to a VDHSEMSTATE data area */
 
VDHQuerySem(SemHandle, SemStatePtr);</pre>
 
 
 
 
=== VDHQuerySem Parameter - SemHandle ===
 
'''SemHandle'''(HVDHSEM) Semaphore handle.
 
 
 
 
 
=== VDHQuerySem Parameter - SemStatePtr ===
 
'''SemStatePtr'''(PVDHSEMSTATE) A pointer to the data area to be filled with the state of the semaphore.
 
SemStatePtr points to a variable defined in VDMM.INC and structured as follows:
 
<pre class="western"> typedef struct  VDHSemState_s {
        UCHAR  vss_SemType;        /* VDH_EVENTSEM/VDH_MUTEXSEM      */
        UCHAR  vss_fOwned;          /* 0 = Not Owned; 1 = Owned        */
        USHORT  vss_fWaiter;        /* 0 = No one waiting; 1 = Waiting */
        USHORT  vss_cRequest;        /* Request count in mutex case    */
        TID    vss_tid;            /* TID of the owner, if owned      */
}VDHSEMSTATE;</pre>
 
 
 
 
 
 
=== VDHQuerySem - Return Value ===
 
None.
 
 
 
 
 
=== VDHQuerySem - Parameters ===
 
'''SemHandle'''(HVDHSEM) Semaphore handle.
 
'''SemStatePtr'''(PVDHSEMSTATE) A pointer to the data area to be filled with the state of the semaphore.
 
SemStatePtr points to a variable defined in VDMM.INC and structured as follows:
 
<pre class="western"> typedef struct  VDHSemState_s {
        UCHAR  vss_SemType;        /* VDH_EVENTSEM/VDH_MUTEXSEM      */
        UCHAR  vss_fOwned;          /* 0 = Not Owned; 1 = Owned        */
        USHORT  vss_fWaiter;        /* 0 = No one waiting; 1 = Waiting */
        USHORT  vss_cRequest;        /* Request count in mutex case    */
        TID    vss_tid;            /* TID of the owner, if owned      */
}VDHSEMSTATE;</pre>
 
 
None.
 
 
 
 
 
=== VDHQuerySem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for state checking services.
 
Notes: The validity of SemStatePtr is not checked. The calling program must pass the address of a valid data area.
 
 
 
 
 
=== VDHQuerySem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQuerySysValue ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function queries a system value.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Index of the system variable handle of the DOS session */
ULONG    Index;      /*  Index values */
ULONG    rc;
 
rc = VDHQuerySysValue(VDMHandle, Index);</pre>
 
 
 
 
=== VDHQuerySysValue - Format ===
 
This function queries a system value.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Index of the system variable handle of the DOS session */
ULONG    Index;      /*  Index values */
ULONG    rc;
 
rc = VDHQuerySysValue(VDMHandle, Index);</pre>
 
 
 
 
=== VDHQuerySysValue Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) Index of the system variable handle of the DOS session to query. A value of 0 (zero) indicates the current DOS session.
 
 
 
 
 
=== VDHQuerySysValue Parameter - Index ===
 
'''Index'''(ULONG) ''VDHQuerySysValue''index values (as defined in VDMM.INC) and descriptions:
 
<pre class="western">Global Values        Ordinal  Type  Units        Range
_____________        _______  ____  _____        _____
 
VDHGSV_DAY              0    ULONG  days          1 &lt; = x &lt; = 31
VDHGSV_MONTH            1    ULONG  months        1 &lt; = x &lt; = 12
VDHGSV_YEAR            2    ULONG  years        1980 &lt; = x &lt; = MAXULONG
VDHGSV_DAYOFWEEK        3    ULONG  days          0 &lt; = x &lt; = 6
VDHGSV_HOUR            4    ULONG  hours        0 &lt; = x &lt; = 24
VDHGSV_MINUTE          5    ULONG  minutes      0 &lt; = x &lt; = 60
VDHGSV_SECOND          6    ULONG  seconds      0 &lt; = x &lt; = 60
VDHGSV_HUNDREDTH        7    ULONG  1/100S        0 &lt; = x &lt; = 100
VDHGSV_SECONDS1970      8    ULONG  seconds      0 &lt; = x &lt; = MAXULONG
VDHGSV_TIMEZONE        9    ULONG  minutes      0 &lt; = x &lt; = MAXULONG
VDHGSV_MSECSBOOT        10    ULONG  milliseconds  0 &lt; = x &lt; = MAXULONG
VDHGSV_TIMERINTERVAL    11    ULONG  milliseconds  0 &lt; = x &lt; = 1000
VDHGSV_DYNVARIATION    12    BOOL                TRUE(nonzero)/FALSE(0)
VDHGSV_MAXWAIT          13    ULONG  seconds      0 &lt; = x &lt; = MAXULONG
VDHGSV_MINTIMESLICE    14    ULONG  milliseconds  0 &lt; = x &lt; = MAXULONG
VDHGSV_MAXTIMESLICE    15    ULONG  milliseconds  0 &lt; = x &lt; = MAXULONG
VDHGSV_YIELD            16    BOOL                TRUE(nonzero)/FALSE(0)
VDHGSV_TCYIELD          17    BOOL                TRUE(nonzero)/FALSE(0)
VDHGSV_VERMAJOR        18    ULONG                0 &lt; = x &lt; = MAXULONG
VDHGSV_VERMINOR        19    ULONG                0 &lt; = x &lt; = MAXULONG
VDHGSV_VERREVISION      20    CHAR                0 &lt; = x &lt; = 255</pre>
 
 
<pre class="western">Global Values        Ordinal  Type  Units        Range
_____________        _______  ____  _____        _____
 
VDHGSV_MACHINETYPE      21    ULONG                MACHINE_TYPE_
VDHGSV_BLACKHOLEADDR    22    PVOID  bytes        0 &lt; = x &lt; = MAXULONG
VDHGSV_BLACKHOLESIZE    23    ULONG  bytes        0 &lt; = x &lt; = MAXULONG
VDHGSV_FGNDSESSIONID    24    ULONG                0 &lt; = x &lt; = MAXSESSIONS
VDHGSV_ARPLADDR        29    ULONG
VDHGSV_MACHINEINFO      30    ULONG                Pointer to System
                                                  Configuration table
VDHGSV_PPOSREGS        31    ULONG                Pointer to POS Regs
                                                  structure
VDHGSV_PICMASK          32    ULONG                Original PIC mask values
 
 
Local Values        Ordinal  Type  Units        Range
____________        _______  ____  _____        _____
 
VDHLSV_HVDM          4096    HVDM
VDHLSV_PID            4097    PID
VDHLSV_PCRF          4098    PCFR
VDHLSV_SESSIONID      4099    ULONG                N &lt; = x &lt; MAXSESSIONS
VDHLSV_FOREGROUND    4100    BOOL                TRUE(nonzero)/FALSE(0)
VDHLSV_RMSIZE        4101    ULONG  KB            0 &lt; x &lt; = 640
VDHLSV_CODEPAGEID    4102    ULONG                See DosGetCP
VDHLSV_PRIORITYCLASS  4103    ULONG                See VDHSetPriority
VDHLSV_PRIORITYLEVEL  4104    ULONG                See VDHSetPriority
VDHLSV_VPICBASE      4105    UCHAR[4]</pre>
 
 
 
 
 
 
=== VDHQuerySysValue Return Value - rc ===
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the value of the system variable. If the value is 0 and ''VDHGetError''returns 0, then 0 is the correct value.
 
Failure If ''VDMHandle''or ''Index''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHQuerySysValue - Parameters ===
 
'''VDMHandle'''(HVDM) Index of the system variable handle of the DOS session to query. A value of 0 (zero) indicates the current DOS session.
 
'''Index'''(ULONG) ''VDHQuerySysValue''index values (as defined in VDMM.INC) and descriptions:
 
<pre class="western">Global Values        Ordinal  Type  Units        Range
_____________        _______  ____  _____        _____
 
VDHGSV_DAY              0    ULONG  days          1 &lt; = x &lt; = 31
VDHGSV_MONTH            1    ULONG  months        1 &lt; = x &lt; = 12
VDHGSV_YEAR            2    ULONG  years        1980 &lt; = x &lt; = MAXULONG
VDHGSV_DAYOFWEEK        3    ULONG  days          0 &lt; = x &lt; = 6
VDHGSV_HOUR            4    ULONG  hours        0 &lt; = x &lt; = 24
VDHGSV_MINUTE          5    ULONG  minutes      0 &lt; = x &lt; = 60
VDHGSV_SECOND          6    ULONG  seconds      0 &lt; = x &lt; = 60
VDHGSV_HUNDREDTH        7    ULONG  1/100S        0 &lt; = x &lt; = 100
VDHGSV_SECONDS1970      8    ULONG  seconds      0 &lt; = x &lt; = MAXULONG
VDHGSV_TIMEZONE        9    ULONG  minutes      0 &lt; = x &lt; = MAXULONG
VDHGSV_MSECSBOOT        10    ULONG  milliseconds  0 &lt; = x &lt; = MAXULONG
VDHGSV_TIMERINTERVAL    11    ULONG  milliseconds  0 &lt; = x &lt; = 1000
VDHGSV_DYNVARIATION    12    BOOL                TRUE(nonzero)/FALSE(0)
VDHGSV_MAXWAIT          13    ULONG  seconds      0 &lt; = x &lt; = MAXULONG
VDHGSV_MINTIMESLICE    14    ULONG  milliseconds  0 &lt; = x &lt; = MAXULONG
VDHGSV_MAXTIMESLICE    15    ULONG  milliseconds  0 &lt; = x &lt; = MAXULONG
VDHGSV_YIELD            16    BOOL                TRUE(nonzero)/FALSE(0)
VDHGSV_TCYIELD          17    BOOL                TRUE(nonzero)/FALSE(0)
VDHGSV_VERMAJOR        18    ULONG                0 &lt; = x &lt; = MAXULONG
VDHGSV_VERMINOR        19    ULONG                0 &lt; = x &lt; = MAXULONG
VDHGSV_VERREVISION      20    CHAR                0 &lt; = x &lt; = 255</pre>
 
 
<pre class="western">Global Values        Ordinal  Type  Units        Range
_____________        _______  ____  _____        _____
 
VDHGSV_MACHINETYPE      21    ULONG                MACHINE_TYPE_
VDHGSV_BLACKHOLEADDR    22    PVOID  bytes        0 &lt; = x &lt; = MAXULONG
VDHGSV_BLACKHOLESIZE    23    ULONG  bytes        0 &lt; = x &lt; = MAXULONG
VDHGSV_FGNDSESSIONID    24    ULONG                0 &lt; = x &lt; = MAXSESSIONS
VDHGSV_ARPLADDR        29    ULONG
VDHGSV_MACHINEINFO      30    ULONG                Pointer to System
                                                  Configuration table
VDHGSV_PPOSREGS        31    ULONG                Pointer to POS Regs
                                                  structure
VDHGSV_PICMASK          32    ULONG                Original PIC mask values
 
 
Local Values        Ordinal  Type  Units        Range
____________        _______  ____  _____        _____
 
VDHLSV_HVDM          4096    HVDM
VDHLSV_PID            4097    PID
VDHLSV_PCRF          4098    PCFR
VDHLSV_SESSIONID      4099    ULONG                N &lt; = x &lt; MAXSESSIONS
VDHLSV_FOREGROUND    4100    BOOL                TRUE(nonzero)/FALSE(0)
VDHLSV_RMSIZE        4101    ULONG  KB            0 &lt; x &lt; = 640
VDHLSV_CODEPAGEID    4102    ULONG                See DosGetCP
VDHLSV_PRIORITYCLASS  4103    ULONG                See VDHSetPriority
VDHLSV_PRIORITYLEVEL  4104    ULONG                See VDHSetPriority
VDHLSV_VPICBASE      4105    UCHAR[4]</pre>
 
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the value of the system variable. If the value is 0 and ''VDHGetError''returns 0, then 0 is the correct value.
 
Failure If ''VDMHandle''or ''Index''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHQuerySysValue - Purpose ===
 
Context Issues: This function can be called in any context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Systems values are of two classes, global and per-DOS session. These classes are distinguished by the prefix of the index name. Variables with prefixes of ''VDHGSV_''are global. Variables with a ''VDHLSV_''prefix are per-DOS session.
 
 
 
 
 
=== VDHQuerySysValue - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQueryVIRQ ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function returns information about the virtual mask, interrupt request flag, interrupt in-service flag, and pending virtual device driver Interrupt Return (IRET) handlers for the specified IRQ, device, or DOS session.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  IRQ handle from DOS session handle */
HIRQ    IRQHandle;  /*  IRQ handle from VDHOpenVIRQ */
ULONG    rc;
 
rc = VDHQueryVIRQ(VDMHandle, IRQHandle);</pre>
 
 
 
 
=== VDHQueryVIRQ - Format ===
 
This function returns information about the virtual mask, interrupt request flag, interrupt in-service flag, and pending virtual device driver Interrupt Return (IRET) handlers for the specified IRQ, device, or DOS session.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  IRQ handle from DOS session handle */
HIRQ    IRQHandle;  /*  IRQ handle from VDHOpenVIRQ */
ULONG    rc;
 
rc = VDHQueryVIRQ(VDMHandle, IRQHandle);</pre>
 
 
 
 
=== VDHQueryVIRQ Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) IRQ handle from ''VDHOpenVIRQ''DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
 
 
 
 
=== VDHQueryVIRQ Parameter - IRQHandle ===
 
'''IRQHandle'''(HIRQ) IRQ handle from ''VDHOpenVIRQ''.
 
 
 
 
 
=== VDHQueryVIRQ Return Value - rc ===
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the IRQ status as a DD of flag bits:
 
VPICQ_REQUEST_PENDING Request is pending for the queried IRQ <br />VPICQ_IN_SERVICE Queried IRQ is in service <br />VPICQ_VIRT_MASK Mask is turned ON for the queried IRQ <br />VPICQ_STAT_IRET_PENDING IRET is pending for the queried IRQ.
 
Failure If ''VDMHandle''or ''IRQHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHQueryVIRQ - Parameters ===
 
'''VDMHandle'''(HVDM) IRQ handle from ''VDHOpenVIRQ''DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
'''IRQHandle'''(HIRQ) IRQ handle from ''VDHOpenVIRQ''.
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the IRQ status as a DD of flag bits:
 
VPICQ_REQUEST_PENDING Request is pending for the queried IRQ <br />VPICQ_IN_SERVICE Queried IRQ is in service <br />VPICQ_VIRT_MASK Mask is turned ON for the queried IRQ <br />VPICQ_STAT_IRET_PENDING IRET is pending for the queried IRQ.
 
Failure If ''VDMHandle''or ''IRQHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHQueryVIRQ - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHQueryVIRQ - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRaiseException ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used to raise an exception, which is reflected to a DOS session as if the exception were caused by the hardware.
 
<pre class="western">#include mvdm.h
 
ULONG    Exception;  /*  An exception number */
ULONG    ErrorCode;  /*  Error code for the exception */
ULONG    ExtraCode;  /*  Extra error code */
BOOL    rc;
 
rc = VDHRaiseException(Exception, ErrorCode,
      ExtraCode);</pre>
 
 
 
 
=== VDHRaiseException - Format ===
 
This function is used to raise an exception, which is reflected to a DOS session as if the exception were caused by the hardware.
 
<pre class="western">#include mvdm.h
 
ULONG    Exception;  /*  An exception number */
ULONG    ErrorCode;  /*  Error code for the exception */
ULONG    ExtraCode;  /*  Extra error code */
BOOL    rc;
 
rc = VDHRaiseException(Exception, ErrorCode,
      ExtraCode);</pre>
 
 
 
 
=== VDHRaiseException Parameter - Exception ===
 
'''Exception'''(ULONG) An exception number that might be caused by the 80386 microprocessor.
 
 
 
 
 
=== VDHRaiseException Parameter - ErrorCode ===
 
'''ErrorCode'''(ULONG) Error code for the exception defined for the 80386 microprocessor.
 
 
 
 
 
=== VDHRaiseException Parameter - ExtraCode ===
 
'''ExtraCode'''(ULONG) Extra error code for DPMI 1.0 page faults.
 
 
 
 
 
=== VDHRaiseException Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHRaiseException - Parameters ===
 
'''Exception'''(ULONG) An exception number that might be caused by the 80386 microprocessor.
 
'''ErrorCode'''(ULONG) Error code for the exception defined for the 80386 microprocessor.
 
'''ExtraCode'''(ULONG) Extra error code for DPMI 1.0 page faults.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHRaiseException - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHRaiseException - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRead ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function reads bytes from a file or device previously opened by ''VDHOpen''.
 
<pre class="western">#include mvdm.h
 
HFILE    FileHandle;    /*  Handle to the file or device to read */
PVOID    ReadBufferPtr;  /*  Address of the buffer to store the bytes read */
ULONG    NumBytes;      /*  Number of bytes to read */
ULONG    rc;
 
rc = VDHRead(FileHandle, ReadBufferPtr, NumBytes);</pre>
 
 
 
 
=== VDHRead - Format ===
 
This function reads bytes from a file or device previously opened by ''VDHOpen''.
 
<pre class="western">#include mvdm.h
 
HFILE    FileHandle;    /*  Handle to the file or device to read */
PVOID    ReadBufferPtr;  /*  Address of the buffer to store the bytes read */
ULONG    NumBytes;      /*  Number of bytes to read */
ULONG    rc;
 
rc = VDHRead(FileHandle, ReadBufferPtr, NumBytes);</pre>
 
 
 
 
=== VDHRead Parameter - FileHandle ===
 
'''FileHandle'''(HFILE) Handle to the file or device to read.
 
 
 
 
 
=== VDHRead Parameter - ReadBufferPtr ===
 
'''ReadBufferPtr'''(PVOID) Address of the buffer to store the bytes read.
 
 
 
 
 
=== VDHRead Parameter - NumBytes ===
 
'''NumBytes'''(ULONG) Number of bytes to read.
 
 
 
 
 
=== VDHRead Return Value - rc ===
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns a count of the number of bytes read; this can be equal to 0 (zero).
 
Failure If the function fails, it returns 0FFFFFFFFH. ''VDHGetError''should be called to determine the nature of the problem. If ''FileHandle''is invalid or this function is called in any context except DOS session-task, a system halt occurs.
 
 
 
 
 
=== VDHRead - Parameters ===
 
'''FileHandle'''(HFILE) Handle to the file or device to read.
 
'''ReadBufferPtr'''(PVOID) Address of the buffer to store the bytes read.
 
'''NumBytes'''(ULONG) Number of bytes to read.
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns a count of the number of bytes read; this can be equal to 0 (zero).
 
Failure If the function fails, it returns 0FFFFFFFFH. ''VDHGetError''should be called to determine the nature of the problem. If ''FileHandle''is invalid or this function is called in any context except DOS session-task, a system halt occurs.
 
 
 
 
 
=== VDHRead - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHRead - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHReadUBuf ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used to read from protected-mode address space as if the read were done at Ring 3. This means any other faults are trapped. All faults are passed on to the DOS session application handler through ''VDHRaiseException''.
 
<pre class="western">#include mvdm.h
 
PVOID    DestBuffer;    /*  Destination buffer for copy. */
ULONG    ByteCount;      /*  Count of bytes */
SEL      Selector;      /*  Application selector */
PULONG    OffsetPointer;  /*  Address of the variable containing the offset */
ULONG    Flag;          /*  Checking controls flag */
BOOL      rc;
 
rc = VDHReadUBuf(DestBuffer, ByteCount, Selector,
      OffsetPointer, Flag);</pre>
 
 
 
 
=== VDHReadUBuf - Format ===
 
This function is used to read from protected-mode address space as if the read were done at Ring 3. This means any other faults are trapped. All faults are passed on to the DOS session application handler through ''VDHRaiseException''.
 
<pre class="western">#include mvdm.h
 
PVOID    DestBuffer;    /*  Destination buffer for copy. */
ULONG    ByteCount;      /*  Count of bytes */
SEL      Selector;      /*  Application selector */
PULONG    OffsetPointer;  /*  Address of the variable containing the offset */
ULONG    Flag;          /*  Checking controls flag */
BOOL      rc;
 
rc = VDHReadUBuf(DestBuffer, ByteCount, Selector,
      OffsetPointer, Flag);</pre>
 
 
 
 
=== VDHReadUBuf Parameter - DestBuffer ===
 
'''DestBuffer'''(PVOID) Destination buffer for copy.
 
 
 
 
 
=== VDHReadUBuf Parameter - ByteCount ===
 
'''ByteCount'''(ULONG) Count of bytes.
 
 
 
 
 
=== VDHReadUBuf Parameter - Selector ===
 
'''Selector'''(SEL) Application selector.
 
 
 
 
 
=== VDHReadUBuf Parameter - OffsetPointer ===
 
'''OffsetPointer'''(PULONG) Address of the variable containing the offset for the start of the read.
 
 
 
 
 
=== VDHReadUBuf Parameter - Flag ===
 
'''Flag'''(ULONG) Flag containing checking controls.
 
Possible values are:
 
VPM_PROT_READ Check for read. <br />VPM_PROT_WRITE Check for write. <br />VPM_FAULT_IF_SU_SET Fault, if supervisor pages. <br />VPM_FAULT_IF_RO Fault, if writing to read-only descriptor. <br />VPM_SEL_PRESENT Caller knows descriptor is present. <br />VPM_SEL_WRITEABLE Caller knows descriptor is writable. <br />VPM_SEL_IS_SS Selector is client's stack. <br />VPM_XCPTRET_ALT After exception, return to alternate mode. For example, if the client was in protected mode when the service was called, return in V86 mode after the exception is handled.
 
 
 
 
 
=== VDHReadUBuf Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if a bad address reference is causing the fault. In this case, ''OffsetPointer''is updated with the address of the fault. For selector faults, ''OffsetPointer''is unchanged.
 
 
 
 
 
=== VDHReadUBuf - Parameters ===
 
'''DestBuffer'''(PVOID) Destination buffer for copy.
 
'''ByteCount'''(ULONG) Count of bytes.
 
'''Selector'''(SEL) Application selector.
 
'''OffsetPointer'''(PULONG) Address of the variable containing the offset for the start of the read.
 
'''Flag'''(ULONG) Flag containing checking controls.
 
Possible values are:
 
VPM_PROT_READ Check for read. <br />VPM_PROT_WRITE Check for write. <br />VPM_FAULT_IF_SU_SET Fault, if supervisor pages. <br />VPM_FAULT_IF_RO Fault, if writing to read-only descriptor. <br />VPM_SEL_PRESENT Caller knows descriptor is present. <br />VPM_SEL_WRITEABLE Caller knows descriptor is writable. <br />VPM_SEL_IS_SS Selector is client's stack. <br />VPM_XCPTRET_ALT After exception, return to alternate mode. For example, if the client was in protected mode when the service was called, return in V86 mode after the exception is handled.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if a bad address reference is causing the fault. In this case, ''OffsetPointer''is updated with the address of the fault. For selector faults, ''OffsetPointer''is unchanged.
 
 
 
 
 
=== VDHReadUBuf - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: If the routine fails, the caller must clean up and exit so that the exception can be simulated to the user. Supervisor pages can be read without faults to avoid the overhead of checking.
 
 
 
 
 
=== VDHReadUBuf - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHReallocPages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function expands or shrinks a memory object.
 
<pre class="western">#include mvdm.h
 
PVOID    ObjectAddress;  /*  Address of the memory object to resize */
ULONG    NumPages;      /*  New size of the memory object (in 4KB pages) */
ULONG    Reserved;      /*  Must be zero */
PVOID    rc;
 
rc = VDHReallocPages(ObjectAddress, NumPages,
      Reserved);</pre>
 
 
 
 
=== VDHReallocPages - Format ===
 
This function expands or shrinks a memory object.
 
<pre class="western">#include mvdm.h
 
PVOID    ObjectAddress;  /*  Address of the memory object to resize */
ULONG    NumPages;      /*  New size of the memory object (in 4KB pages) */
ULONG    Reserved;      /*  Must be zero */
PVOID    rc;
 
rc = VDHReallocPages(ObjectAddress, NumPages,
      Reserved);</pre>
 
 
 
 
=== VDHReallocPages Parameter - ObjectAddress ===
 
'''ObjectAddress'''(PVOID) Address of the memory object to reallocate or resize.
 
 
 
 
 
=== VDHReallocPages Parameter - NumPages ===
 
'''NumPages'''(ULONG) The new size of the memory object (in 4KB pages).
 
 
 
 
 
=== VDHReallocPages Parameter - Reserved ===
 
'''Reserved'''(ULONG) Must be set to zero.
 
 
 
 
 
=== VDHReallocPages Return Value - rc ===
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns that address of the reallocated memory block.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If the memory object at ''ObjectAddress''was not allocated by ''VDHAllocPages''or ''VDHReallocPages'', or if the ''NumPages''or ''Reserved''parameters are invalid, a system halt occurs.
 
 
 
 
 
=== VDHReallocPages - Parameters ===
 
'''ObjectAddress'''(PVOID) Address of the memory object to reallocate or resize.
 
'''NumPages'''(ULONG) The new size of the memory object (in 4KB pages).
 
'''Reserved'''(ULONG) Must be set to zero.
 
'''rc'''(PVOID) - returns
 
Success If the function is successful, it returns that address of the reallocated memory block.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If the memory object at ''ObjectAddress''was not allocated by ''VDHAllocPages''or ''VDHReallocPages'', or if the ''NumPages''or ''Reserved''parameters are invalid, a system halt occurs.
 
 
 
 
 
=== VDHReallocPages - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: Any allocations that are not in the terminating DOS session's private area must be released by using ''VDHFreePages''.
 
Notes: When an allocation made with ''VDHAllocPages''is shrunk by ''VDHReallocPages'', the linear range between the end of the allocation and the original end of the allocation remains available for object growth without movement. If the linear range encompassed by the new size was reserved ( with ''VDHReservePages''), reallocation occurs without movement. Reallocation also succeeds without movement if the object was larger than the desired size since it last moved. Regardless of ''VDHReallocPages''activity, all pages in the allocation retain the same properties, that is, fixed, system, and physical.
 
 
 
 
 
=== VDHReallocPages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRegisterAPI ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used to register a virtual device driver's API handler that can be called by a DOS or DPMI application in the DOS session. A V86- mode or protected-mode (or both) API handler is set for a particular virtual device driver. Each virtual device driver must register with a unique virtual device driver name. This service provides a mechanism for DOS applications to communicate directly with the virtual device driver.
 
<pre class="western">#include mvdm.h
 
PSZ        VDDName;    /*  Pointer to the name of the virtual device driver */
PFNHook    pfnV86Hook;  /*  V86-mode hook routine address */
PFNHook    pfnVPMHook;  /*  VPM-mode hook routine address */
BOOL      rc;
 
rc = VDHRegisterAPI(VDDName, pfnV86Hook, pfnVPMHook);</pre>
 
 
 
 
=== VDHRegisterAPI - Format ===
 
This function is used to register a virtual device driver's API handler that can be called by a DOS or DPMI application in the DOS session. A V86- mode or protected-mode (or both) API handler is set for a particular virtual device driver. Each virtual device driver must register with a unique virtual device driver name. This service provides a mechanism for DOS applications to communicate directly with the virtual device driver.
 
<pre class="western">#include mvdm.h
 
PSZ        VDDName;    /*  Pointer to the name of the virtual device driver */
PFNHook    pfnV86Hook;  /*  V86-mode hook routine address */
PFNHook    pfnVPMHook;  /*  VPM-mode hook routine address */
BOOL      rc;
 
rc = VDHRegisterAPI(VDDName, pfnV86Hook, pfnVPMHook);</pre>
 
 
 
 
=== VDHRegisterAPI Parameter - VDDName ===
 
'''VDDName'''(PSZ) Pointer to the name of the virtual device driver. Maximum length is MAXLENXDD.
 
 
 
 
 
=== VDHRegisterAPI Parameter - pfnV86Hook ===
 
'''pfnV86Hook'''(PFNHook) V86-mode hook routine address (NULL if no V86-mode handler is needed).
 
 
 
 
 
=== VDHRegisterAPI Parameter - pfnVPMHook ===
 
'''pfnVPMHook'''(PFNHook) VPM-mode hook routine address (NULL if no VPM-mode handler is needed).
 
 
 
 
 
=== VDHRegisterAPI Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success Returns TRUE
 
Failure Returns FALSE
 
 
 
 
 
=== VDHRegisterAPI - Parameters ===
 
'''VDDName'''(PSZ) Pointer to the name of the virtual device driver. Maximum length is MAXLENXDD.
 
'''pfnV86Hook'''(PFNHook) V86-mode hook routine address (NULL if no V86-mode handler is needed).
 
'''pfnVPMHook'''(PFNHook) VPM-mode hook routine address (NULL if no VPM-mode handler is needed).
 
'''rc'''(BOOL) - returns
 
Success Returns TRUE
 
Failure Returns FALSE
 
 
 
 
 
=== VDHRegisterAPI - Purpose ===
 
Context Issues: This function can only be called in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function. The hook(s) are freed when the DOS session is terminated .
 
Notes:
 
Hook routine:
 
<pre class="western">VOID HOOKENTRY pfnHook(p,prcf)
    ENTRY    PVOID p-reserved
              PCRF pcrf-pointer to client register frame
    EXIT      None
    CONTEXT  DOS session-task</pre>
DOS or DPMI applications issue the following INT 2F calls to determine if they are running under OS/2, and then get the virtual device driver API entry point.
 
Get OS/2 version (DOS or DPMI applications can use this INT 2F call to get the OS/2 version):
 
<pre class="western">    ENTRY    AX = 0x4010
    EXIT      If OS/2 is running:
                  AX = 0
                  BX = OS/2 version (example:BX = 1400 for 2.0)
              If OS/2 is not present, AX is unchanged</pre>
Get virtual device driver API entry points. DOS or DPMI applications can use this INT 2F call to get the address to call the virtual device driver entry points. If the INT 2F is issued in V86 mode, an address that calls the V86 virtual device driver API handler is returned. If the INT 2F call is issued in protected-mode, an address that corresponds to the protected- mode API handler is returned.
 
<pre class="western">    ENTRY    AX = 0x4011
              DS:(E)SI = pointer to ASCIIZ name registered
                                with VDHRegisterAPI
    EXIT      If VDD API handler exists:
                  ES:DI = address to call to invoke handler
              If handler is not registered:
                  ES:DI = NULL</pre>
The DOS or DPMI application can then issue a far call to the address returned to invoke the virtual device driver API handler.
 
 
 
 
 
=== VDHRegisterAPI - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRegisterDMAChannel ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used by virtual device drivers to register with the virtual DMA device driver (VDMA) to get the ownership of a DMA channel.
 
<pre class="western">#include mvdm.h
 
ULONG    DMAChannel;      /*  DMA channel */
PFNDMA    DMAHandlerFunc;  /*  The virtual device driver's DMA-handling routine */
BOOL      rc;
 
rc = VDHRegisterDMAChannel(DMAChannel, DMAHandlerFunc);</pre>
 
 
 
 
=== VDHRegisterDMAChannel - Format ===
 
This function is used by virtual device drivers to register with the virtual DMA device driver (VDMA) to get the ownership of a DMA channel.
 
<pre class="western">#include mvdm.h
 
ULONG    DMAChannel;      /*  DMA channel */
PFNDMA    DMAHandlerFunc;  /*  The virtual device driver's DMA-handling routine */
BOOL      rc;
 
rc = VDHRegisterDMAChannel(DMAChannel, DMAHandlerFunc);</pre>
 
 
 
 
=== VDHRegisterDMAChannel Parameter - DMAChannel ===
 
'''DMAChannel'''(ULONG) DMA channel.
 
 
 
 
 
=== VDHRegisterDMAChannel Parameter - DMAHandlerFunc ===
 
'''DMAHandlerFunc'''(PFNDMA) The virtual device driver's DMA-handler function.
 
The interface for the DMA-handler routine is as follows:
 
<pre class="western"> BOOL HOOKENTRY (hvdm, iEvent)
 
ENTRY
    HVDM  hvdm  - DOS session requesting DMA
    ULONG iEvent - VDD_DMA_MASKOFF (Start DMA, Event)
                    VDD_DMA_MASK    (Stop  DMA, Event)
EXIT
    SUCCESS - returns nonzero
              If VDD_DMA_MASKOFF,
                  the virtual DMA device driver will program the DMA
              If VDD_DMA_MASK, don't care
    FAILURE - returns 0 (zero)</pre>
 
 
 
 
 
 
=== VDHRegisterDMAChannel Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns 1.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHRegisterDMAChannel - Parameters ===
 
'''DMAChannel'''(ULONG) DMA channel.
 
'''DMAHandlerFunc'''(PFNDMA) The virtual device driver's DMA-handler function.
 
The interface for the DMA-handler routine is as follows:
 
<pre class="western"> BOOL HOOKENTRY (hvdm, iEvent)
 
ENTRY
    HVDM  hvdm  - DOS session requesting DMA
    ULONG iEvent - VDD_DMA_MASKOFF (Start DMA, Event)
                    VDD_DMA_MASK    (Stop  DMA, Event)
EXIT
    SUCCESS - returns nonzero
              If VDD_DMA_MASKOFF,
                  the virtual DMA device driver will program the DMA
              If VDD_DMA_MASK, don't care
    FAILURE - returns 0 (zero)</pre>
 
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns 1.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHRegisterDMAChannel - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: In the case of VDD_DMA_MASKOFF, the virtual device driver gets the hardware ownership and unhooks all the ports. If hardware ownership is not available immediately, it blocks the DOS session. On VDD_DMA_MASK, the virtual device driver returns the ownership and hooks back the ports.
 
If the DOS application programs the hardware handled by a virtual device driver first, and then programs the DMA, this virtual device driver receives ownership of hardware, unhooks all ports on first port access, and arms a timer for a safe period. This is a preventive measure to protect the system from errant I/O to DMA ports. If the timer fires, the virtual device driver releases the hardware. In this case, the virtual device driver does nothing when the virtual DMA device driver later calls with VDD_DMA_MASKOFF .
 
It is the virtual device driver's responsibility (in DMAHandlerFunc) to handle the unavailability of hardware ownership. This means the virtual device driver must put up the pop-up and suspend (or terminate) the DOS session. The virtual device driver passes the interrupt notification to the virtual DMA device driver before simulating that interrupt to the DOS session, if it owns the hardware.
 
In between VDD_DMA_MASKOFF and VDD_DMA_MASK events, the virtual DMA device driver always returns the physical DMA state, if the application polls its status or transfer count. This is appropriate because the virtual device driver owns the device during this period. VDD_DMA_MASK event notification takes place before actually masking the register in DMA. VDD_DMA_MASKOFF takes place after masking off the DMA.
 
DMA Channel 4 is not supported.
 
 
 
 
 
=== VDHRegisterDMAChannel - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRegisterProperty ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function registers a virtual device driver property with the DOS Session Manager.
 
<pre class="western">#include mvdm.h
 
PSZ        PropertyName;    /*  Property name pointer */
PSZ        Reserved;        /*  Must be set to 0 */
ULONG      Reserved;        /*  Must be set to 0 */
VPTYPE      PropertyType;    /*  Property type */
VPORD      PropertyOrdinal;  /*  Property ordinal */
ULONG      PropertyFlag;    /*  Property flag */
PVOID      DefaultValue;    /*  Default value of the property */
PVOID      ValidationData;  /*  Validation data */
PFNVDHRP    ValidationFunc;  /*  Pointer to a virtual device driver property function */
BOOL        rc;
 
rc = VDHRegisterProperty(PropertyName, Reserved,
      Reserved, PropertyType, PropertyOrdinal,
      PropertyFlag, DefaultValue, ValidationData,
      ValidationFunc);</pre>
 
 
 
 
=== VDHRegisterProperty - Format ===
 
This function registers a virtual device driver property with the DOS Session Manager.
 
<pre class="western">#include mvdm.h
 
PSZ        PropertyName;    /*  Property name pointer */
PSZ        Reserved;        /*  Must be set to 0 */
ULONG      Reserved;        /*  Must be set to 0 */
VPTYPE      PropertyType;    /*  Property type */
VPORD      PropertyOrdinal;  /*  Property ordinal */
ULONG      PropertyFlag;    /*  Property flag */
PVOID      DefaultValue;    /*  Default value of the property */
PVOID      ValidationData;  /*  Validation data */
PFNVDHRP    ValidationFunc;  /*  Pointer to a virtual device driver property function */
BOOL        rc;
 
rc = VDHRegisterProperty(PropertyName, Reserved,
      Reserved, PropertyType, PropertyOrdinal,
      PropertyFlag, DefaultValue, ValidationData,
      ValidationFunc);</pre>
 
 
 
 
=== VDHRegisterProperty Parameter - PropertyName ===
 
'''PropertyName'''(PSZ) Pointer to an ASCIIZ string containing the property name . Maximum length is 40 characters.
 
 
 
 
 
=== VDHRegisterProperty Parameter - Reserved ===
 
'''Reserved'''(PSZ) Must be set to 0 (zero).
 
 
 
 
 
=== VDHRegisterProperty Parameter - Reserved ===
 
'''Reserved'''(ULONG) Must be set to 0 (zero).
 
 
 
 
 
=== VDHRegisterProperty Parameter - PropertyType ===
 
'''PropertyType'''(VPTYPE) Property type.
 
Values are:
 
VDMP_BOOL 0-Boolean <br />VDMP_INT 1-Integer. DD size, but only DW is valid <br />VDMP_ENUM 2-Enumeration <br />VDMP_STRING 3-ASCIIZ string <br />VDMP_MLSTR 4-Multi-line string, separated by linefeed (0AH)
 
 
 
 
 
=== VDHRegisterProperty Parameter - PropertyOrdinal ===
 
'''PropertyOrdinal'''(VPORD) Property ordinal.
 
Values are:
 
VDMP_ORD_OTHER 0-Custom virtual device driver property <br />VDMP_ORD_KERNEL 1-ASCIIZ path of DOS kernel <br />VDMP_ORD_SHELL 2-ASCIIZ path of DOS_SHELL <br />VDMP_ORD_RMSIZE 3-Integer size of DOS box (128KB-640KB) <br />VDMP_ORD_FCB 4-Integer total FCBs <br />VDMP_ORD_FCB2 5-Integer FCBs immune to close LRUing <br />VDMP_ORD_BREAK 6-Boolean Break flag <br />VDMP_ORD_DOSDD 7-Multi-line string DOS_DEVICE <br />VDMP_ORD_VMBOOT 8-ASCIIZ string virtual machine boot drives <br />VDMP_ORD_VERSION 10-Multi-line string fake version entries <br />VDMP_ORD_DOS_UMB 11-Boolean flag. DOS_UMB <br />VDMP_ORD_DOS_HIGH 12-Boolean flag. DOS_HIGH <br />VDMP_ORD_LASTDRIVE 13-ASCIIZ DOS_LASTDRIVE <br />VDMP_ORD_FILES 14-Integer total FILES
 
 
 
 
 
=== VDHRegisterProperty Parameter - PropertyFlag ===
 
'''PropertyFlag'''(ULONG) Property flag.
 
Possible value:
 
VDMP_CREATE Property can be specified only at DOS session creation. Any change to the property after DOS session creation is ignored.
 
 
 
 
 
=== VDHRegisterProperty Parameter - DefaultValue ===
 
'''DefaultValue'''(PVOID) Default value of the property.
 
The format of this field depends on the value of PropertyType:
 
VDMP_BOOL DefaultValue is interpreted as a BOOL (Boolean) value. <br />VDMP_INT DefaultValue is interpreted as a DD value. Only the low half is used (the high half is ignored) so this is more similar to a DW than a DD. <br />VDMP_ENUM DefaultValue is interpreted as a pointer to an ASCIIZ string. <br />VDMP_STRING DefaultValue is interpreted as a pointer to an ASCIIZ string. <br />VDMP_MLSTR DefaultValue is interpreted as a pointer to an ASCIIZ string.
 
 
 
 
 
=== VDHRegisterProperty Parameter - ValidationData ===
 
'''ValidationData'''(PVOID) Validation data.
 
The value of this field depends on the value of PropertyType.
 
VDMP_BOOL ValidationData is NULL. The user is expected to validate Booleans .
 
VDMP_INT ValidationData is a pointer to a VPBOUND structure:
 
VPBOUND Limits for VDMP_INT properties. Note that maximum '''&gt;'''minimum must hold, the range of maximum to minimum must be a multiple of step, and step= 1 implies that all values between minimum and maximum are valid:
 
<pre class="western"> typedef struct VPBOUND_s {
    USHORT  min;    // minimum allowed value
    USHORT  max;    // maximum allowed value
    USHORT  step;  // increment between values
} VPBOUND;
 
typedef VPBOUND *PVPBOUND;</pre>
VDMP_ENUM ValidationData is a pointer to a set of ASCIIZ strings terminated by a zero byte, which is the allowed set of responses. The Shell uses this to construct a list or combination box for the user to pick from. Empty (&quot;\ 0&quot;) strings are not allowed.
 
VDMP_STRING ValidationData is a DD that is the maximum allowed string length (including the NULL terminator).
 
VDMP_MLSTR ValidationData is a DD that is the maximum allowed string length (including the NULL terminator).
 
 
 
 
 
=== VDHRegisterProperty Parameter - ValidationFunc ===
 
'''ValidationFunc'''(PFNVDHRP) Function that validates and accepts changes to this property for a running DOS session. Ignored if VDMP_CREATE is specified in conjunction with VDMP_BOOL, VDMP_INT, or VDMP_ENUM.
 
The interface for the ValidationFunc is defined as follows:
 
<pre class="western"> #define VDHPROP_VALIDATE    0x00000000L
#define VDHPROP_SET        0x00000001L
 
ULONG EXPENTRY fnvdhrp (ULONG op, HVDM hvdm, ULONG cb, PSZ pch);</pre>
PFNVDHRP is a pointer to a property function of the virtual device driver that performs property setting and validation. This routine is required for any property that does not specify VDMP_CREATE. Set operations can be requested any time after a DOS session is created. The validation operation can be requested at any time, even before a DOS session is created. Validation is requested only for VDMP_STRING and VDMP_MLSTR types because all other types can be validated using the information supplied by VDHRegisterProperty.
 
<pre class="western">Parameter      Data Type      Description
_________      _________      ___________
 
op              ULONG          Operation to perform.  See the following
                                parameter.
 
hvdm            HVDM            Handle of DOS session.  Undefined if op =
                                VDHPROP_VALIDATE.
 
cb              ULONG          Count of bytes pointed by pch.  See the
                                following parameter.
 
pch            PSZ            Pointer to the value set or validate. See the
                                following parameter.</pre>
op Operation to perform (enumeration):
 
VDHPROP_VALIDATE Validate property for any process. Only called for VDMP_ STRING and VDMP_MLSTR properties. <br />VDHPROP_SET Set an already validated property for specified hvdm. The return code is ignored.
 
cb Count of bytes pointed to by pch. Value depends upon PropertyType:
 
VDMPROP_BOOL Undefined <br />VDMPROP_INT Undefined <br />VDMPROP_ENUM Length of ASCIIZ string including NULL terminator <br />VDMPROP_STRING Length of ASCIIZ string including NULL terminator <br />VDMPROP_MLSTR Length of ASCIIZ string including NULL terminator
 
pch Value to set/validate. The format depends on the property type:
 
VDMPROP_BOOL pch is interpreted as a BOOL (Boolean). Value 0 is FALSE; a nonzero value is TRUE.
 
VDMPROP_INT pch is interpreted as a DD, and is guaranteed to meet the registered bounds.
 
VDMPROP_ENUM pch points to an ASCIIZ string, and is guaranteed to be one of the registered enumeration strings.
 
VDMPROP_STRING pch points to an ASCIIZ string, and is guaranteed to be equal to or less than the registered maximum string length.
 
VDMPROP_MLSTR pch points to an ASCIIZ string. Multiple lines are separated by a line feed (0x0A). It is guaranteed to be less than or equal to the registered maximum string length.
 
 
 
 
 
=== VDHRegisterProperty Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. A system halt occurs if:
 
*Any of the pointers (PropertyName, HelpFile, ValidationData, or ValidationFunc) are invalid <br />*PropertyFlag or PropertyType are invalid <br />*A VPBOUND structure has invalid contents <br />*The maximum string length for a VDMP_STRING is less than the length of the default string value
 
 
 
 
 
=== VDHRegisterProperty - Parameters ===
 
'''PropertyName'''(PSZ) Pointer to an ASCIIZ string containing the property name . Maximum length is 40 characters.
 
'''Reserved'''(PSZ) Must be set to 0 (zero).
 
'''Reserved'''(ULONG) Must be set to 0 (zero).
 
'''PropertyType'''(VPTYPE) Property type.
 
Values are:
 
VDMP_BOOL 0-Boolean <br />VDMP_INT 1-Integer. DD size, but only DW is valid <br />VDMP_ENUM 2-Enumeration <br />VDMP_STRING 3-ASCIIZ string <br />VDMP_MLSTR 4-Multi-line string, separated by linefeed (0AH)
 
'''PropertyOrdinal'''(VPORD) Property ordinal.
 
Values are:
 
VDMP_ORD_OTHER 0-Custom virtual device driver property <br />VDMP_ORD_KERNEL 1-ASCIIZ path of DOS kernel <br />VDMP_ORD_SHELL 2-ASCIIZ path of DOS_SHELL <br />VDMP_ORD_RMSIZE 3-Integer size of DOS box (128KB-640KB) <br />VDMP_ORD_FCB 4-Integer total FCBs <br />VDMP_ORD_FCB2 5-Integer FCBs immune to close LRUing <br />VDMP_ORD_BREAK 6-Boolean Break flag <br />VDMP_ORD_DOSDD 7-Multi-line string DOS_DEVICE <br />VDMP_ORD_VMBOOT 8-ASCIIZ string virtual machine boot drives <br />VDMP_ORD_VERSION 10-Multi-line string fake version entries <br />VDMP_ORD_DOS_UMB 11-Boolean flag. DOS_UMB <br />VDMP_ORD_DOS_HIGH 12-Boolean flag. DOS_HIGH <br />VDMP_ORD_LASTDRIVE 13-ASCIIZ DOS_LASTDRIVE <br />VDMP_ORD_FILES 14-Integer total FILES
 
'''PropertyFlag'''(ULONG) Property flag.
 
Possible value:
 
VDMP_CREATE Property can be specified only at DOS session creation. Any change to the property after DOS session creation is ignored.
 
'''DefaultValue'''(PVOID) Default value of the property.
 
The format of this field depends on the value of PropertyType:
 
VDMP_BOOL DefaultValue is interpreted as a BOOL (Boolean) value. <br />VDMP_INT DefaultValue is interpreted as a DD value. Only the low half is used (the high half is ignored) so this is more similar to a DW than a DD. <br />VDMP_ENUM DefaultValue is interpreted as a pointer to an ASCIIZ string. <br />VDMP_STRING DefaultValue is interpreted as a pointer to an ASCIIZ string. <br />VDMP_MLSTR DefaultValue is interpreted as a pointer to an ASCIIZ string.
 
'''ValidationData'''(PVOID) Validation data.
 
The value of this field depends on the value of PropertyType.
 
VDMP_BOOL ValidationData is NULL. The user is expected to validate Booleans .
 
VDMP_INT ValidationData is a pointer to a VPBOUND structure:
 
VPBOUND Limits for VDMP_INT properties. Note that maximum '''&gt;'''minimum must hold, the range of maximum to minimum must be a multiple of step, and step= 1 implies that all values between minimum and maximum are valid:
 
<pre class="western"> typedef struct VPBOUND_s {
    USHORT  min;    // minimum allowed value
    USHORT  max;    // maximum allowed value
    USHORT  step;  // increment between values
} VPBOUND;
 
typedef VPBOUND *PVPBOUND;</pre>
VDMP_ENUM ValidationData is a pointer to a set of ASCIIZ strings terminated by a zero byte, which is the allowed set of responses. The Shell uses this to construct a list or combination box for the user to pick from. Empty (&quot;\ 0&quot;) strings are not allowed.
 
VDMP_STRING ValidationData is a DD that is the maximum allowed string length (including the NULL terminator).
 
VDMP_MLSTR ValidationData is a DD that is the maximum allowed string length (including the NULL terminator).
 
'''ValidationFunc'''(PFNVDHRP) Function that validates and accepts changes to this property for a running DOS session. Ignored if VDMP_CREATE is specified in conjunction with VDMP_BOOL, VDMP_INT, or VDMP_ENUM.
 
The interface for the ValidationFunc is defined as follows:
 
<pre class="western"> #define VDHPROP_VALIDATE    0x00000000L
#define VDHPROP_SET        0x00000001L
 
ULONG EXPENTRY fnvdhrp (ULONG op, HVDM hvdm, ULONG cb, PSZ pch);</pre>
PFNVDHRP is a pointer to a property function of the virtual device driver that performs property setting and validation. This routine is required for any property that does not specify VDMP_CREATE. Set operations can be requested any time after a DOS session is created. The validation operation can be requested at any time, even before a DOS session is created. Validation is requested only for VDMP_ STRING and VDMP_MLSTR types because all other types can be validated using the information supplied by VDHRegisterProperty.
 
<pre class="western">Parameter      Data Type      Description
_________      _________      ___________
 
op              ULONG          Operation to perform.  See the following
                                parameter.
 
hvdm            HVDM            Handle of DOS session.  Undefined if op =
                                VDHPROP_VALIDATE.
 
cb              ULONG          Count of bytes pointed by pch.  See the
                                following parameter.
 
pch            PSZ            Pointer to the value set or validate. See the
                                following parameter.</pre>
op Operation to perform (enumeration):
 
VDHPROP_VALIDATE Validate property for any process. Only called for VDMP_ STRING and VDMP_MLSTR properties. <br />VDHPROP_SET Set an already validated property for specified hvdm. The return code is ignored.
 
cb Count of bytes pointed to by pch. Value depends upon PropertyType:
 
VDMPROP_BOOL Undefined <br />VDMPROP_INT Undefined <br />VDMPROP_ENUM Length of ASCIIZ string including NULL terminator <br />VDMPROP_STRING Length of ASCIIZ string including NULL terminator <br />VDMPROP_MLSTR Length of ASCIIZ string including NULL terminator
 
pch Value to set/validate. The format depends on the property type:
 
VDMPROP_BOOL pch is interpreted as a BOOL (Boolean). Value 0 is FALSE; a nonzero value is TRUE.
 
VDMPROP_INT pch is interpreted as a DD, and is guaranteed to meet the registered bounds.
 
VDMPROP_ENUM pch points to an ASCIIZ string, and is guaranteed to be one of the registered enumeration strings.
 
VDMPROP_STRING pch points to an ASCIIZ string, and is guaranteed to be equal to or less than the registered maximum string length.
 
VDMPROP_MLSTR pch points to an ASCIIZ string. Multiple lines are separated by a line feed (0x0A). It is guaranteed to be less than or equal to the registered maximum string length.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. A system halt occurs if:
 
*Any of the pointers (PropertyName, HelpFile, ValidationData, or ValidationFunc) are invalid <br />*PropertyFlag or PropertyType are invalid <br />*A VPBOUND structure has invalid contents <br />*The maximum string length for a VDMP_STRING is less than the length of the default string value
 
 
 
 
 
=== VDHRegisterProperty - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: VDHQueryProperty is used to obtain the value of a virtual device driver property for a particular DOS session.
 
 
 
 
 
=== VDHRegisterProperty - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRegisterVDD ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function registers virtual device driver entry points for use by other virtual device drivers (through ''VDHOpenVDD''and ''VDHRequestVDD''), and by OS/2 applications (through ''DosOpenVDD''and ''DosRequestVDD'').
 
<pre class="western">#include mvdm.h
 
PSZ          VDDName;    /*  Pointer to the name of the virtual device driver */
PFNSYSREQ    DosReqFcn;  /*  Function for use by DosRequestVDD */
PFNDEVREQ    VDDReqFcn;  /*  Function for use by VDHRequestVDD */
BOOL        rc;
 
rc = VDHRegisterVDD(VDDName, DosReqFcn, VDDReqFcn);</pre>
 
 
 
 
=== VDHRegisterVDD - Format ===
 
This function registers virtual device driver entry points for use by other virtual device drivers (through ''VDHOpenVDD''and ''VDHRequestVDD''), and by OS/2 applications (through ''DosOpenVDD''and ''DosRequestVDD'').
 
<pre class="western">#include mvdm.h
 
PSZ          VDDName;    /*  Pointer to the name of the virtual device driver */
PFNSYSREQ    DosReqFcn;  /*  Function for use by DosRequestVDD */
PFNDEVREQ    VDDReqFcn;  /*  Function for use by VDHRequestVDD */
BOOL        rc;
 
rc = VDHRegisterVDD(VDDName, DosReqFcn, VDDReqFcn);</pre>
 
 
 
 
=== VDHRegisterVDD Parameter - VDDName ===
 
'''VDDName'''(PSZ) Pointer to the name of the virtual device driver. Maximum length is MAXLENXDD.
 
 
 
 
 
=== VDHRegisterVDD Parameter - DosReqFcn ===
 
'''DosReqFcn'''(PFNSYSREQ) Function used by ''DosRequestVDD''. NULL, if none.
 
The interface for the ''DosReqFcn''is:
 
<pre class="western"> RETCODE EXPENTRY DosReqFcn(ulCmd,SGid,nbIn,pReqIn,nbOut,pReqOut)
 
ENTRY
    SGID  SGid    - Screen Group ID
    ULONG ulCmd  - Command
    ULONG cbIn    - Input buffer size
    PVOID pReqIn  - Input packet
    ULONG cbOut  - Output buffer size
    PVOID pReqOut - Output packet
 
EXIT
    VDDREQ_PASS    - DOS session manager calls the next routine
                      registered under same name
    TRUE (nonzero)  - Return failure (For APIs, 0 is success)
    FALSE (0)      - Return the caller success</pre>
 
 
 
 
 
 
=== VDHRegisterVDD Parameter - VDDReqFcn ===
 
'''VDDReqFcn'''(PFNDEVREQ) Function used by ''VDHRequestVDD''. NULL, if none.
 
The interface for the ''VDDReqFcn''is:
 
<pre class="western"> BOOL EXPENTRY VDDReqFcn(hvdm,ulCmd,pReqIn,pReqOut)
 
ENTRY
    HVDM    hvdm    - DOS session handle
    ULONG  ulCmd  - Command
    PVOID  pReqIn  - Input packet
    PVOID  pReqOut - Output packet
 
EXIT
    VDDREQ_PASS    - DOS Session Manager calls the next routine
                      registered under same name
    TRUE (nonzero)  - Return success (For virtual DevHlp services, 1 is success)
    FALSE (0)      - Return the caller failure</pre>
 
 
 
 
 
 
=== VDHRegisterVDD Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0. If this function is called with invalid parameters or in an incorrect context, a system halt occurs.
 
 
 
 
 
=== VDHRegisterVDD - Parameters ===
 
'''VDDName'''(PSZ) Pointer to the name of the virtual device driver. Maximum length is MAXLENXDD.
 
'''DosReqFcn'''(PFNSYSREQ) Function used by ''DosRequestVDD''. NULL, if none.
 
The interface for the ''DosReqFcn''is:
 
<pre class="western"> RETCODE EXPENTRY DosReqFcn(ulCmd,SGid,nbIn,pReqIn,nbOut,pReqOut)
 
ENTRY
    SGID  SGid    - Screen Group ID
    ULONG ulCmd  - Command
    ULONG cbIn    - Input buffer size
    PVOID pReqIn  - Input packet
    ULONG cbOut  - Output buffer size
    PVOID pReqOut - Output packet
 
EXIT
    VDDREQ_PASS    - DOS session manager calls the next routine
                      registered under same name
    TRUE (nonzero)  - Return failure (For APIs, 0 is success)
    FALSE (0)      - Return the caller success</pre>
 
 
'''VDDReqFcn'''(PFNDEVREQ) Function used by ''VDHRequestVDD''. NULL, if none.
 
The interface for the ''VDDReqFcn''is:
 
<pre class="western"> BOOL EXPENTRY VDDReqFcn(hvdm,ulCmd,pReqIn,pReqOut)
 
ENTRY
    HVDM    hvdm    - DOS session handle
    ULONG  ulCmd  - Command
    PVOID  pReqIn  - Input packet
    PVOID  pReqOut - Output packet
 
EXIT
    VDDREQ_PASS    - DOS Session Manager calls the next routine
                      registered under same name
    TRUE (nonzero)  - Return success (For virtual DevHlp services, 1 is success)
    FALSE (0)      - Return the caller failure</pre>
 
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0. If this function is called with invalid parameters or in an incorrect context, a system halt occurs.
 
 
 
 
 
=== VDHRegisterVDD - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Session Terminations: The virtual device driver must communicate with any virtual device driver or OS/2 clients, to ensure that the resources for the terminating DOS session are freed.
 
Notes: If a virtual device driver fails in its INIT routine after registering (through ''VDHRegisterVDD''), the deregistration is done automatically at the time the virtual device driver is unloaded. Because two or more virtual device drivers can register the same name (''VDDName''), the DOS Session Manager calls each virtual device driver's routine in turn, until one of them returns a nonzero value.
 
Note that the order of the calling sequence is not consistent.
 
 
 
 
 
=== VDHRegisterVDD - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHReleaseCodePageFont ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function releases a code page font loaded with ''VDHGetCodePageFont''. If system memory was allocated to hold the specified font, this call will free that memory.
 
<pre class="western">#include mvdm.h
 
PVOID    FontPtr;  /*  Pointer returned by VDHGetCodePageFont */
 
VDHReleaseCodePageFont(FontPtr);</pre>
 
 
 
 
=== VDHReleaseCodePageFont - Format ===
 
This function releases a code page font loaded with ''VDHGetCodePageFont''. If system memory was allocated to hold the specified font, this call will free that memory.
 
<pre class="western">#include mvdm.h
 
PVOID    FontPtr;  /*  Pointer returned by VDHGetCodePageFont */
 
VDHReleaseCodePageFont(FontPtr);</pre>
 
 
 
 
=== VDHReleaseCodePageFont Parameter - FontPtr ===
 
'''FontPtr'''(PVOID) Pointer returned in ''FontAddress''by ''VDHGetCodePageFont''.
 
 
 
 
 
=== VDHReleaseCodePageFont - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''FontPtr''is not valid, a system halt occurs.
 
 
 
 
 
=== VDHReleaseCodePageFont - Parameters ===
 
'''FontPtr'''(PVOID) Pointer returned in ''FontAddress''by ''VDHGetCodePageFont''.
 
Success If the function is successful, it returns nothing.
 
Failure If ''FontPtr''is not valid, a system halt occurs.
 
 
 
 
 
=== VDHReleaseCodePageFont - Purpose ===
 
Context Issues: This function can be called only in the DOS session task context.
 
DOS Session Terminations: The virtual device driver must call this function for any code page fonts loaded for this DOS session.
 
 
 
 
 
=== VDHReleaseCodePageFont - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHReleaseMutexSem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function releases the ownership of a mutex semaphore. If the request count becomes 0 (zero), the highest priority semaphore is awakened.
 
<pre class="western">#include mvdm.h
 
HVDHSEM    MutexSemHandle;  /*  Handle of the semaphore to be released */
 
VDHReleaseMutexSem(MutexSemHandle);</pre>
 
 
 
 
=== VDHReleaseMutexSem - Format ===
 
This function releases the ownership of a mutex semaphore. If the request count becomes 0 (zero), the highest priority semaphore is awakened.
 
<pre class="western">#include mvdm.h
 
HVDHSEM    MutexSemHandle;  /*  Handle of the semaphore to be released */
 
VDHReleaseMutexSem(MutexSemHandle);</pre>
 
 
 
 
=== VDHReleaseMutexSem Parameter - MutexSemHandle ===
 
'''MutexSemHandle'''(HVDHSEM) Handle of the semaphore to be released.
 
 
 
 
 
=== VDHReleaseMutexSem - Return Value ===
 
Success If the function is successful, it returns nothing and the semaphore in ''MutexSemHandle''is released.
 
Failure If the virtual device driver that called ''VDHReleaseMutexSem''is not the owner of the semaphore to be released, or if ''MutexSemHandle''invalid, a system halt occurs.
 
 
 
 
 
=== VDHReleaseMutexSem - Parameters ===
 
'''MutexSemHandle'''(HVDHSEM) Handle of the semaphore to be released.
 
Success If the function is successful, it returns nothing and the semaphore in ''MutexSemHandle''is released.
 
Failure If the virtual device driver that called ''VDHReleaseMutexSem''is not the owner of the semaphore to be released, or if ''MutexSemHandle''invalid, a system halt occurs.
 
 
 
 
 
=== VDHReleaseMutexSem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHReleaseMutexSem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRemoveFaultHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function removes the page fault handler hook for the specified DOS session page range.
 
<pre class="western">#include mvdm.h
 
HVDM          VDMHandle;              /*  DOS session handle.  0 = current DOS session */
PVOID        StartingAddress;        /*  Starting linear address */
ULONG        Pages;                  /*  Number of pages */
PFAULTHOOK    PageFaultHandlerFcnPtr;  /*  Function supplied to VDHInstallFaultHook */
 
VDHRemoveFaultHook(VDMHandle, StartingAddress,
      Pages, PageFaultHandlerFcnPtr);</pre>
 
 
 
 
=== VDHRemoveFaultHook - Format ===
 
This function removes the page fault handler hook for the specified DOS session page range.
 
<pre class="western">#include mvdm.h
 
HVDM          VDMHandle;              /*  DOS session handle.  0 = current DOS session */
PVOID        StartingAddress;        /*  Starting linear address */
ULONG        Pages;                  /*  Number of pages */
PFAULTHOOK    PageFaultHandlerFcnPtr;  /*  Function supplied to VDHInstallFaultHook */
 
VDHRemoveFaultHook(VDMHandle, StartingAddress,
      Pages, PageFaultHandlerFcnPtr);</pre>
 
 
 
 
=== VDHRemoveFaultHook Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
 
 
 
 
=== VDHRemoveFaultHook Parameter - StartingAddress ===
 
'''StartingAddress'''(PVOID) Starting linear address.
 
 
 
 
 
=== VDHRemoveFaultHook Parameter - Pages ===
 
'''Pages'''(ULONG) Number of pages.
 
 
 
 
 
=== VDHRemoveFaultHook Parameter - PageFaultHandlerFcnPtr ===
 
'''PageFaultHandlerFcnPtr'''(PFAULTHOOK) Function supplied to ''VDHInstallFaultHook''. This is used to verify that the calling virtual device driver is the one that installed the fault hook.
 
 
 
 
 
=== VDHRemoveFaultHook - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If any of the input parameters are invalid, a system halt occurs.
 
 
 
 
 
=== VDHRemoveFaultHook - Parameters ===
 
'''VDMHandle'''(HVDM) DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
'''StartingAddress'''(PVOID) Starting linear address.
 
'''Pages'''(ULONG) Number of pages.
 
'''PageFaultHandlerFcnPtr'''(PFAULTHOOK) Function supplied to ''VDHInstallFaultHook''. This is used to verify that the calling virtual device driver is the one that installed the fault hook.
 
Success If the function is successful, it returns nothing.
 
Failure If any of the input parameters are invalid, a system halt occurs.
 
 
 
 
 
=== VDHRemoveFaultHook - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: Any fault hooks for the terminating DOS session must be released.
 
 
 
 
 
=== VDHRemoveFaultHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRemoveIOHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function must be called with ''StartingPort''and ''NumPorts''to remove the I /O hooks for the specified I/O ports. Port hooks cannot be removed for a subset of the range of ports hooked by ''VDHInstallIOHook''.
 
<pre class="western">#include mvdm.h
 
ULONG    Reserved;      /*  Reserved.  Must be set to 0 (zero). */
PORT    StartingPort;  /*  Starting port number */
ULONG    NumPorts;      /*  Number of ports in the range */
PIOH    IOPortHook;    /*  Pointer to installed I/O hook entry */
 
VDHRemoveIOHook(Reserved, StartingPort, NumPorts,
      IOPortHook);</pre>
 
 
 
 
=== VDHRemoveIOHook - Format ===
 
This function must be called with ''StartingPort''and ''NumPorts''to remove the I /O hooks for the specified I/O ports. Port hooks cannot be removed for a subset of the range of ports hooked by ''VDHInstallIOHook''.
 
<pre class="western">#include mvdm.h
 
ULONG    Reserved;      /*  Reserved.  Must be set to 0 (zero). */
PORT    StartingPort;  /*  Starting port number */
ULONG    NumPorts;      /*  Number of ports in the range */
PIOH    IOPortHook;    /*  Pointer to installed I/O hook entry */
 
VDHRemoveIOHook(Reserved, StartingPort, NumPorts,
      IOPortHook);</pre>
 
 
 
 
=== VDHRemoveIOHook Parameter - Reserved ===
 
'''Reserved'''(ULONG) Reserved. Must be set to 0.
 
 
 
 
 
=== VDHRemoveIOHook Parameter - StartingPort ===
 
'''StartingPort'''(PORT) Starting port number.
 
 
 
 
 
=== VDHRemoveIOHook Parameter - NumPorts ===
 
'''NumPorts'''(ULONG) Number of ports in the range.
 
 
 
 
 
=== VDHRemoveIOHook Parameter - IOPortHook ===
 
'''IOPortHook'''(PIOH) Pointer to installed I/O hook entry. This parameter is used to verify that the calling virtual device driver is the one that installed the I/O hook.
 
 
 
 
 
=== VDHRemoveIOHook - Return Value ===
 
Success If the function was successful, it returns nothing.
 
Failure If ''IOPortHookEntry''is invalid or if ''StartingPort''or ''NumPorts''are out of range, a system halt occurs.
 
 
 
 
 
=== VDHRemoveIOHook - Parameters ===
 
'''Reserved'''(ULONG) Reserved. Must be set to 0.
 
'''StartingPort'''(PORT) Starting port number.
 
'''NumPorts'''(ULONG) Number of ports in the range.
 
'''IOPortHook'''(PIOH) Pointer to installed I/O hook entry. This parameter is used to verify that the calling virtual device driver is the one that installed the I/O hook.
 
Success If the function was successful, it returns nothing.
 
Failure If ''IOPortHookEntry''is invalid or if ''StartingPort''or ''NumPorts''are out of range, a system halt occurs.
 
 
 
 
 
=== VDHRemoveIOHook - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function. I/O hooks are automatically removed during DOS session termination.
 
Notes: If the ''IOPortHook''is in instance data, the address passed ''VDHInstallIOHook''must be the same address passed to ''VDHRemoveIOHook''or ''VDHSetIOHookState''.
 
 
 
 
 
=== VDHRemoveIOHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHReportPeek ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function reports DOS session polling activity. A counter of idle polling activity is incremented. If the count exceeds a threshold, the current DOS session is put to sleep for a period.
 
<pre class="western">#include mvdm.h
 
ULONG    PeekWeight;  /*  Value to add to the idle counter */
 
VDHReportPeek(PeekWeight);</pre>
 
 
 
 
=== VDHReportPeek - Format ===
 
This function reports DOS session polling activity. A counter of idle polling activity is incremented. If the count exceeds a threshold, the current DOS session is put to sleep for a period.
 
<pre class="western">#include mvdm.h
 
ULONG    PeekWeight;  /*  Value to add to the idle counter */
 
VDHReportPeek(PeekWeight);</pre>
 
 
 
 
=== VDHReportPeek Parameter - PeekWeight ===
 
'''PeekWeight'''(ULONG) Value to add to the idle counter.
 
 
 
 
 
=== VDHReportPeek - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If the current process is not a DOS session, a system halt occurs.
 
 
 
 
 
=== VDHReportPeek - Parameters ===
 
'''PeekWeight'''(ULONG) Value to add to the idle counter.
 
Success If the function is successful, it returns nothing.
 
Failure If the current process is not a DOS session, a system halt occurs.
 
 
 
 
 
=== VDHReportPeek - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Any virtual device driver that can detect idle polling activity can call this service to report it. If the sum of peek weights exceeds 64KB in a single VDHGSV_MSECSBOOT clock tick (see [[00822.htm|VDHQuerySysValue]]), the DOS session is considered idle. It is the responsibility of the virtual device driver to calibrate its peek weight. This depends on machine speed and the Ring 0 trap overhead time, and therefore cannot be calibrated from measuring peek rate under DOS.
 
Note that testing the time before the count ensures that new tests begin at the first peek in a time slice. This allows use of a very short test period .
 
 
 
 
 
=== VDHReportPeek - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRequestMutexSem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function requests the ownership of a mutex semaphore. If the semaphore is owned and the caller is not the owner, the thread will block. If the caller is the owner, a request count is incremented. Request calls can be nested. A maximum of 65,535 (64KB) requests are allowed for each semaphore at any one time. Exceeding this limit results in a system halt.
 
<pre class="western">#include mvdm.h
 
HVDHSEM    MutexSemHandle;  /*  Mutex semaphore handle */
ULONG      Timeout;        /*  Timeout (in milliseconds) */
BOOL      rc;
 
rc = VDHRequestMutexSem(MutexSemHandle, Timeout);</pre>
 
 
 
 
=== VDHRequestMutexSem - Format ===
 
This function requests the ownership of a mutex semaphore. If the semaphore is owned and the caller is not the owner, the thread will block. If the caller is the owner, a request count is incremented. Request calls can be nested. A maximum of 65,535 (64KB) requests are allowed for each semaphore at any one time. Exceeding this limit results in a system halt.
 
<pre class="western">#include mvdm.h
 
HVDHSEM    MutexSemHandle;  /*  Mutex semaphore handle */
ULONG      Timeout;        /*  Timeout (in milliseconds) */
BOOL      rc;
 
rc = VDHRequestMutexSem(MutexSemHandle, Timeout);</pre>
 
 
 
 
=== VDHRequestMutexSem Parameter - MutexSemHandle ===
 
'''MutexSemHandle'''(HVDHSEM) Mutex semaphore handle.
 
 
 
 
 
=== VDHRequestMutexSem Parameter - Timeout ===
 
'''Timeout'''(ULONG) Number of milliseconds to wait before timing out the semaphore.
 
 
 
 
 
=== VDHRequestMutexSem Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns 1.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. An invalid semaphore will result in a system halt. A system halt also occurs if the request count crosses the 64KB limit.
 
 
 
 
 
=== VDHRequestMutexSem - Parameters ===
 
'''MutexSemHandle'''(HVDHSEM) Mutex semaphore handle.
 
'''Timeout'''(ULONG) Number of milliseconds to wait before timing out the semaphore.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns 1.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. An invalid semaphore will result in a system halt. A system halt also occurs if the request count crosses the 64KB limit.
 
 
 
 
 
=== VDHRequestMutexSem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHRequestMutexSem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRequestVDD ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function requests an operation of a virtual device driver. This service is also used for communication between two or more virtual device drivers where dynamic linkage between them is not appropriate.
 
<pre class="western">#include mvdm.h
 
HVDD    VDDHandle;            /*  Virtual device driver handle */
HVDM    VDMHandle;            /*  DOS session handle */
ULONG    Command;              /*  Command requested */
PVOID    InputRequestPacket;  /*  Pointer to the input packet */
PVOID    OutputRequestPacket;  /*  Pointer to the output packet */
BOOL    rc;
 
rc = VDHRequestVDD(VDDHandle, VDMHandle, Command,
      InputRequestPacket, OutputRequestPacket);</pre>
 
 
 
 
=== VDHRequestVDD - Format ===
 
This function requests an operation of a virtual device driver. This service is also used for communication between two or more virtual device drivers where dynamic linkage between them is not appropriate.
 
<pre class="western">#include mvdm.h
 
HVDD    VDDHandle;            /*  Virtual device driver handle */
HVDM    VDMHandle;            /*  DOS session handle */
ULONG    Command;              /*  Command requested */
PVOID    InputRequestPacket;  /*  Pointer to the input packet */
PVOID    OutputRequestPacket;  /*  Pointer to the output packet */
BOOL    rc;
 
rc = VDHRequestVDD(VDDHandle, VDMHandle, Command,
      InputRequestPacket, OutputRequestPacket);</pre>
 
 
 
 
=== VDHRequestVDD Parameter - VDDHandle ===
 
'''VDDHandle'''(HVDD) Handle to a virtual device driver.
 
 
 
 
 
=== VDHRequestVDD Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) Handle to a DOS session.
 
 
 
 
 
=== VDHRequestVDD Parameter - Command ===
 
'''Command'''(ULONG) Command requested.
 
 
 
 
 
=== VDHRequestVDD Parameter - InputRequestPacket ===
 
'''InputRequestPacket'''(PVOID) Pointer to the input packet.
 
 
 
 
 
=== VDHRequestVDD Parameter - OutputRequestPacket ===
 
'''OutputRequestPacket'''(PVOID) Pointer to the output packet.
 
 
 
 
 
=== VDHRequestVDD Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''VDDHandle''or ''VDMHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHRequestVDD - Parameters ===
 
'''VDDHandle'''(HVDD) Handle to a virtual device driver.
 
'''VDMHandle'''(HVDM) Handle to a DOS session.
 
'''Command'''(ULONG) Command requested.
 
'''InputRequestPacket'''(PVOID) Pointer to the input packet.
 
'''OutputRequestPacket'''(PVOID) Pointer to the output packet.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''VDDHandle''or ''VDMHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHRequestVDD - Purpose ===
 
Context Issues: This function can be called in the task or the interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Every ''VDHRequestVDD''procedure registered under the virtual device driver name associated with the given handle is called until one returns a nonzero value. No assumption should be made about the order of the calling sequence.
 
The virtual device driver worker routine sets the error with ''VDHSetError''when it returns 0 (zero). If the calling virtual device driver is registered under the same name as the virtual device driver handle, then its entry point is also called. Furthermore, the DOS Session Manager does not prevent any of the called virtual device drivers from issuing another ''VDHRequestVDD''.
 
 
 
 
 
=== VDHRequestVDD - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHReservePages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function reserves a range of linear addresses for later use with ''VDHMapPages''or ''VDHAllocPages''. A reserved area cannot contain a mixture of pages set by ''VDHMapPages''and ''VDHAllocPages'', but it can be used successively with either one.
 
<pre class="western">#include mvdm.h
 
PVOID    StartingAddress;  /*  Starting address of the linear memory to reserve */
ULONG    NumPages;        /*  Number of pages to reserve */
BOOL    rc;
 
rc = VDHReservePages(StartingAddress, NumPages);</pre>
 
 
 
 
=== VDHReservePages - Format ===
 
This function reserves a range of linear addresses for later use with ''VDHMapPages''or ''VDHAllocPages''. A reserved area cannot contain a mixture of pages set by ''VDHMapPages''and ''VDHAllocPages'', but it can be used successively with either one.
 
<pre class="western">#include mvdm.h
 
PVOID    StartingAddress;  /*  Starting address of the linear memory to reserve */
ULONG    NumPages;        /*  Number of pages to reserve */
BOOL    rc;
 
rc = VDHReservePages(StartingAddress, NumPages);</pre>
 
 
 
 
=== VDHReservePages Parameter - StartingAddress ===
 
'''StartingAddress'''(PVOID) Starting address of the linear memory to reserve. Must be page aligned and must be less than 110000H (1MB + 64KB).
 
 
 
 
 
=== VDHReservePages Parameter - NumPages ===
 
'''NumPages'''(ULONG) Number of pages to reserve.
 
 
 
 
 
=== VDHReservePages Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value and the pages are reserved for later access.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''StartingAddress''or ''NumPages''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHReservePages - Parameters ===
 
'''StartingAddress'''(PVOID) Starting address of the linear memory to reserve. Must be page aligned and must be less than 110000H (1MB + 64KB).
 
'''NumPages'''(ULONG) Number of pages to reserve.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value and the pages are reserved for later access.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''StartingAddress''or ''NumPages''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHReservePages - Purpose ===
 
Context Issues: This function can be called in the initialization and DOS session-task contexts. In the initialization context, the reservation affects only the global linear memory map. In the DOS session-task context, reservations affect only the local linear memory map.
 
DOS Session Terminations: There are no DOS session termination implications for this function. The DOS Session Manager will clean up these reservations when the DOS session terminates.
 
 
 
 
 
=== VDHReservePages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHResetEventSem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function resets an event semaphore.
 
<pre class="western">#include mvdm.h
 
HVDHSEM    EventSemHandle;  /*  Handle to the event semaphore to be reset */
 
VDHResetEventSem(EventSemHandle);</pre>
 
 
 
 
=== VDHResetEventSem - Format ===
 
This function resets an event semaphore.
 
<pre class="western">#include mvdm.h
 
HVDHSEM    EventSemHandle;  /*  Handle to the event semaphore to be reset */
 
VDHResetEventSem(EventSemHandle);</pre>
 
 
 
 
=== VDHResetEventSem Parameter - EventSemHandle ===
 
'''EventSemHandle'''(HVDHSEM) Handle to the event semaphore to be reset.
 
 
 
 
 
=== VDHResetEventSem - Return Value ===
 
Success If the function is successful, it returns nothing and the semaphore is reset.
 
Failure Resetting a semaphore that is invalid or is already reset causes a system halt to occur.
 
 
 
 
 
=== VDHResetEventSem - Parameters ===
 
'''EventSemHandle'''(HVDHSEM) Handle to the event semaphore to be reset.
 
Success If the function is successful, it returns nothing and the semaphore is reset.
 
Failure Resetting a semaphore that is invalid or is already reset causes a system halt to occur.
 
 
 
 
 
=== VDHResetEventSem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHResetEventSem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSeek ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function seeks to a specified position within a file previously opened by ''VDHOpen''.
 
<pre class="western">#include mvdm.h
 
HFILE    FileHandle;    /*  Handle to the file */
ULONG    NewOffset;    /*  Offset of the new file-pointer position */
ULONG    MoveTypeFlag;  /*  Type of move (absolute, relative) */
ULONG    rc;
 
rc = VDHSeek(FileHandle, NewOffset, MoveTypeFlag);</pre>
 
 
 
 
=== VDHSeek - Format ===
 
This function seeks to a specified position within a file previously opened by ''VDHOpen''.
 
<pre class="western">#include mvdm.h
 
HFILE    FileHandle;    /*  Handle to the file */
ULONG    NewOffset;    /*  Offset of the new file-pointer position */
ULONG    MoveTypeFlag;  /*  Type of move (absolute, relative) */
ULONG    rc;
 
rc = VDHSeek(FileHandle, NewOffset, MoveTypeFlag);</pre>
 
 
 
 
=== VDHSeek Parameter - FileHandle ===
 
'''FileHandle'''(HFILE) Handle to the file.
 
 
 
 
 
=== VDHSeek Parameter - NewOffset ===
 
'''NewOffset'''(ULONG) Offset to the new file-pointer position. Depending on the value of ''MoveTypeFlag'', this can be the offset from the beginning of the file, the ending of the file, or the current position of the file-pointer.
 
 
 
 
 
=== VDHSeek Parameter - MoveTypeFlag ===
 
'''MoveTypeFlag'''(ULONG) Indicates what type of move is being done.
 
Possible values are:
 
VDHSK_ABSOLUTE Move file-pointer to a location relative to the beginning of the file <br />VDHSK_CURRENT_POSITION Move file-pointer relative to its current position <br />VDHSK_END_OF_FILE Move file-pointer to a location relative to the end of the file
 
 
 
 
 
=== VDHSeek Return Value - rc ===
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the new current absolute position of the file-pointer within the file.
 
Failure If the function fails, it returns 0FFFFFFFFH. ''VDHGetError''should be called to determine the nature of the problem. If ''FileHandle''is invalid, or if this function is not called in the DOS session-task context, a system halt occurs.
 
 
 
 
 
=== VDHSeek - Parameters ===
 
'''FileHandle'''(HFILE) Handle to the file.
 
'''NewOffset'''(ULONG) Offset to the new file-pointer position. Depending on the value of ''MoveTypeFlag'', this can be the offset from the beginning of the file, the ending of the file, or the current position of the file-pointer.
 
'''MoveTypeFlag'''(ULONG) Indicates what type of move is being done.
 
Possible values are:
 
VDHSK_ABSOLUTE Move file-pointer to a location relative to the beginning of the file <br />VDHSK_CURRENT_POSITION Move file-pointer relative to its current position <br />VDHSK_END_OF_FILE Move file-pointer to a location relative to the end of the file
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns the new current absolute position of the file-pointer within the file.
 
Failure If the function fails, it returns 0FFFFFFFFH. ''VDHGetError''should be called to determine the nature of the problem. If ''FileHandle''is invalid, or if this function is not called in the DOS session-task context, a system halt occurs.
 
 
 
 
 
=== VDHSeek - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHSeek - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSendVEOI ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function sends a virtual End-Of-Interrupt (EOI) signal to the Virtual Programmable Interrupt Controller (VPIC), and clears the in-service state of the IRQ for the calling device. The EOI handler for the IRQ is called, if one exists.
 
<pre class="western">#include mvdm.h
 
HIRQ    IRQHandle;  /*  IRQ handle */
 
VDHSendVEOI(IRQHandle);</pre>
 
 
 
 
=== VDHSendVEOI - Format ===
 
This function sends a virtual End-Of-Interrupt (EOI) signal to the Virtual Programmable Interrupt Controller (VPIC), and clears the in-service state of the IRQ for the calling device. The EOI handler for the IRQ is called, if one exists.
 
<pre class="western">#include mvdm.h
 
HIRQ    IRQHandle;  /*  IRQ handle */
 
VDHSendVEOI(IRQHandle);</pre>
 
 
 
 
=== VDHSendVEOI Parameter - IRQHandle ===
 
'''IRQHandle'''(HIRQ) IRQ handle.
 
 
 
 
 
=== VDHSendVEOI - Return Value ===
 
Success If the function was successful, it returns nothing.
 
Failure If ''IRQHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHSendVEOI - Parameters ===
 
'''IRQHandle'''(HIRQ) IRQ handle.
 
Success If the function was successful, it returns nothing.
 
Failure If ''IRQHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHSendVEOI - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHSendVEOI - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetDosDevice ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function links a DOS device driver into the chain of DOS device drivers for a DOS session.
 
<pre class="western">#include mvdm.h
 
VPDOSDDTYPE    vpDosDD;  /*  V86 FAR address of the DOS device driver header */
BOOL          rc;
 
rc = VDHSetDosDevice(vpDosDD);</pre>
 
 
 
 
=== VDHSetDosDevice - Format ===
 
This function links a DOS device driver into the chain of DOS device drivers for a DOS session.
 
<pre class="western">#include mvdm.h
 
VPDOSDDTYPE    vpDosDD;  /*  V86 FAR address of the DOS device driver header */
BOOL          rc;
 
rc = VDHSetDosDevice(vpDosDD);</pre>
 
 
 
 
=== VDHSetDosDevice Parameter - vpDosDD ===
 
'''vpDosDD'''(VPDOSDDTYPE) V86 FAR address of the DOS device driver header. This header (and any headers chained to it) are entered into the DOS device driver list for this DOS session.
 
 
 
 
 
=== VDHSetDosDevice Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHSetDosDevice - Parameters ===
 
'''vpDosDD'''(VPDOSDDTYPE) V86 FAR address of the DOS device driver header. This header (and any headers chained to it) are entered into the DOS device driver list for this DOS session.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHSetDosDevice - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context (DOS session creation only).
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHSetDosDevice - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetError ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function sets the error code for return by ''VDHGetError''.
 
<pre class="western">#include mvdm.h
 
ULONG    ErrorCode;  /*  Error code to set */
 
VDHSetError(ErrorCode);</pre>
 
 
 
 
=== VDHSetError - Format ===
 
This function sets the error code for return by ''VDHGetError''.
 
<pre class="western">#include mvdm.h
 
ULONG    ErrorCode;  /*  Error code to set */
 
VDHSetError(ErrorCode);</pre>
 
 
 
 
=== VDHSetError Parameter - ErrorCode ===
 
'''ErrorCode'''(ULONG) Error code to set for ''VDHGetError''.
 
 
 
 
 
=== VDHSetError - Return Value ===
 
None.
 
 
 
 
 
=== VDHSetError - Parameters ===
 
'''ErrorCode'''(ULONG) Error code to set for ''VDHGetError''.
 
None.
 
 
 
 
 
=== VDHSetError - Purpose ===
 
Context Issues: This function can be called in any context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This function is intended for use by any virtual device driver that offers dynamic link services to other virtual device drivers. Most of the base errors are defined in BSEERR.INC. Where possible, these definitions are used when returning errors.
 
 
 
 
 
=== VDHSetError - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetFlags ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function sets the DOS session's Flags Register to specified values.
 
<pre class="western">#include mvdm.h
 
ULONG    FlagValue;  /*  DOS session flag value */
 
VDHSetFlags(FlagValue);</pre>
 
 
 
 
=== VDHSetFlags - Format ===
 
This function sets the DOS session's Flags Register to specified values.
 
<pre class="western">#include mvdm.h
 
ULONG    FlagValue;  /*  DOS session flag value */
 
VDHSetFlags(FlagValue);</pre>
 
 
 
 
=== VDHSetFlags Parameter - FlagValue ===
 
'''FlagValue'''(ULONG) DOS session flag value that sets the flag register of the DOS session.
 
 
 
 
 
=== VDHSetFlags - Return Value ===
 
None.
 
 
 
 
 
=== VDHSetFlags - Parameters ===
 
'''FlagValue'''(ULONG) DOS session flag value that sets the flag register of the DOS session.
 
None.
 
 
 
 
 
=== VDHSetFlags - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Virtual device drivers must use this interface instead of the client register frame pointer to change the DOS session's flags. Changes to the interrupt flag and the I/O Privilege Level (IOPL) field must be under the control of 8086 emulation so that ''VDHArmSTIHook''works correctly.
 
Nested Task (NT) and Resume Flag (RF) flags are cleared, the virtual 8086 Mode (VM) flag is set, and the IOPL field is left unchanged. This function does not take effect until the operating system returns to V86 mode.
 
 
 
 
 
=== VDHSetFlags - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetIOHookState ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used to enable and disable I/O port trapping for a range of ports.
 
<pre class="western">#include mvdm.h
 
ULONG    Reserved;      /*  Reserved.  Must be set to 0 */
PORT    StartingPort;  /*  Starting port number */
ULONG    NumPorts;      /*  Number of ports in the range */
PIOH    IOPortHook;    /*  Pointer used to install I/O hooks */
BOOL    EnableFlag;    /*  FLag for setting I/O hooks */
 
VDHSetIOHookState(Reserved, StartingPort,
      NumPorts, IOPortHook, EnableFlag);</pre>
 
 
 
 
=== VDHSetIOHookState - Format ===
 
This function is used to enable and disable I/O port trapping for a range of ports.
 
<pre class="western">#include mvdm.h
 
ULONG    Reserved;      /*  Reserved.  Must be set to 0 */
PORT    StartingPort;  /*  Starting port number */
ULONG    NumPorts;      /*  Number of ports in the range */
PIOH    IOPortHook;    /*  Pointer used to install I/O hooks */
BOOL    EnableFlag;    /*  FLag for setting I/O hooks */
 
VDHSetIOHookState(Reserved, StartingPort,
      NumPorts, IOPortHook, EnableFlag);</pre>
 
 
 
 
=== VDHSetIOHookState Parameter - Reserved ===
 
'''Reserved'''(ULONG) Reserved. Must be set to 0 (zero).
 
 
 
 
 
=== VDHSetIOHookState Parameter - StartingPort ===
 
'''StartingPort'''(PORT) Starting port number.
 
 
 
 
 
=== VDHSetIOHookState Parameter - NumPorts ===
 
'''NumPorts'''(ULONG) Number of ports in the range.
 
 
 
 
 
=== VDHSetIOHookState Parameter - IOPortHook ===
 
'''IOPortHook'''(PIOH) Pointer used to install I/O hooks. This is used to verify that the calling virtual device driver is the one that installed the I/O hooks.
 
 
 
 
 
=== VDHSetIOHookState Parameter - EnableFlag ===
 
'''EnableFlag'''(BOOL) Flag for setting I/O hooks.
 
TRUE (Non-zero). Enable I/O hooks. <br />FALSE (0). Disable I/O hooks.
 
 
 
 
 
=== VDHSetIOHookState - Return Value ===
 
Success If the function was successful, it returns nothing.
 
Failure If ''IOPortHook''is invalid, or if ''StartingPort''or ''NumPorts''are out of range, or if ''StartingPort''and ''NumPorts''overlap a range of ports previously marked as ''VDHIIH_ALWAYS_TRAP''by ''VDHInstallIOHook'', a system halt occurs.
 
 
 
 
 
=== VDHSetIOHookState - Parameters ===
 
'''Reserved'''(ULONG) Reserved. Must be set to 0 (zero).
 
'''StartingPort'''(PORT) Starting port number.
 
'''NumPorts'''(ULONG) Number of ports in the range.
 
'''IOPortHook'''(PIOH) Pointer used to install I/O hooks. This is used to verify that the calling virtual device driver is the one that installed the I/O hooks.
 
'''EnableFlag'''(BOOL) Flag for setting I/O hooks.
 
TRUE (Non-zero). Enable I/O hooks. <br />FALSE (0). Disable I/O hooks.
 
Success If the function was successful, it returns nothing.
 
Failure If ''IOPortHook''is invalid, or if ''StartingPort''or ''NumPorts''are out of range, or if ''StartingPort''and ''NumPorts''overlap a range of ports previously marked as ''VDHIIH_ALWAYS_TRAP''by ''VDHInstallIOHook'', a system halt occurs.
 
 
 
 
 
=== VDHSetIOHookState - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: If the ''IOPortHook''is in instance data, the address passed to ''VDHInstallIOHook''must be the same address passed to ''VDHRemoveIOHook''or ''VDHSetIOHookState''. When trapping is enabled, the I/O port hooks for the specified range get control when a DOS session does I/O to that range. When trapping is disabled, DOS session I/O goes directly to the physical hardware ports. None of the ports in the range can be marked as VDHIIH_ ALWAYS_TRAP by ''VDHInstallIOHook''.
 
 
 
 
 
=== VDHSetIOHookState - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetPriority ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function adjusts a DOS session's scheduler priority class and level. Priority levels within each priority class range from 0-31.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;        /*  Handle to the DOS session with the priority to change */
ULONG    ActionClassFlag;  /*  Dual purpose flag, Action and Class */
LONG    NewPriority;      /*  Change from the DOS session's previous priority level */
 
VDHSetPriority(VDMHandle, ActionClassFlag,
      NewPriority);</pre>
 
 
 
 
=== VDHSetPriority - Format ===
 
This function adjusts a DOS session's scheduler priority class and level. Priority levels within each priority class range from 0-31.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;        /*  Handle to the DOS session with the priority to change */
ULONG    ActionClassFlag;  /*  Dual purpose flag, Action and Class */
LONG    NewPriority;      /*  Change from the DOS session's previous priority level */
 
VDHSetPriority(VDMHandle, ActionClassFlag,
      NewPriority);</pre>
 
 
 
 
=== VDHSetPriority Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session with the priority to change.
 
 
 
 
 
=== VDHSetPriority Parameter - ActionClassFlag ===
 
'''ActionClassFlag'''(ULONG) A dual-purpose flag.
 
The ''Class''component of ''ActionClassFlag''indicates the class to which the DOS session should be changed. The ''Action''component of the ''ActionClassFlag''allows the virtual device driver to manage when the priority is changed, and when to start, end, or continue use of the class. See &quot;Notes&quot; under Purpose.
 
The value of the ''Class''component can be one of the following:
 
VDHSP_TIME_CRITICAL Highest priority <br />VDHSP_SERVER Highest priority <br />VDHSP_REGULAR Highest priority <br />VDHSP_IDLE Lowest priority <br />VDHSP_NO_CHANGE Do not change the DOS session's class
 
The value of the ''Action''component can be one of the following:
 
VDHSP_START_USE Start use of a class <br />VDHSP_CONTINUE_USE Continue use of a class <br />VDHSP_END_USE End use of a class <br />VDHSP_DEFAULT_ACTION If no action is specified, the default class is changed
 
 
 
 
 
=== VDHSetPriority Parameter - NewPriority ===
 
'''NewPriority'''(LONG) Change from the DOS session's previous priority level.
 
 
 
 
 
=== VDHSetPriority - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''VDMHandle''or ''ActionClassFlag''are invalid, a system halt occurs.
 
 
 
 
 
=== VDHSetPriority - Parameters ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session with the priority to change.
 
'''ActionClassFlag'''(ULONG) A dual-purpose flag.
 
The ''Class''component of ''ActionClassFlag''indicates the class to which the DOS session should be changed. The ''Action''component of the ''ActionClassFlag''allows the virtual device driver to manage when the priority is changed, and when to start, end, or continue use of the class. See &quot;Notes&quot; under Purpose.
 
The value of the ''Class''component can be one of the following:
 
VDHSP_TIME_CRITICAL Highest priority <br />VDHSP_SERVER Highest priority <br />VDHSP_REGULAR Highest priority <br />VDHSP_IDLE Lowest priority <br />VDHSP_NO_CHANGE Do not change the DOS session's class
 
The value of the ''Action''component can be one of the following:
 
VDHSP_START_USE Start use of a class <br />VDHSP_CONTINUE_USE Continue use of a class <br />VDHSP_END_USE End use of a class <br />VDHSP_DEFAULT_ACTION If no action is specified, the default class is changed
 
'''NewPriority'''(LONG) Change from the DOS session's previous priority level.
 
Success If the function is successful, it returns nothing.
 
Failure If ''VDMHandle''or ''ActionClassFlag''are invalid, a system halt occurs.
 
 
 
 
 
=== VDHSetPriority - Purpose ===
 
Context Issues: This function can be called in the task or interrupt contexts.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: A count of the current users is maintained at each class. The actual priority class in effect at any time is always the highest priority class with current declared users. When there are no declared users, the default class is used. Changes to a class other than the effective class are made to saved values. These changes take effect when the class becomes the effective class.
 
The caller must signal when it begins use of the class, when it makes changes within the class, and when it finishes with the class. The typical user would make one or more changes to priority at a particular class, and finish the series of changes at the class. The virtual device driver uses the VDHSP_START_USE and VDHSP_END_USE flags at the first and last calls within the class, and the VDHSP_CONTINUE_USE flag for changes in between.
 
The default class is normally VDHSP_REGULAR unless the class or ''NewPriority''is changed without declaring a user (that is, without specifying a start, continue, or end action flag). This allows a user interface to adjust the default priority of a DOS session.
 
 
 
 
 
=== VDHSetPriority - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetVIRR ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function sets the Virtual Interrupt Request Register (VIRR) in the Virtual Programmable Interrupt Controller (VPIC) of the specified DOS session for the IRQ specified. This causes an interrupt to be simulated to the DOS session.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  DOS session handle */
HIRQ    IRQHandle;  /*  Handle from VDHOpenVIRQ */
 
VDHSetVIRR(VDMHandle, IRQHandle);</pre>
 
 
 
 
=== VDHSetVIRR - Format ===
 
This function sets the Virtual Interrupt Request Register (VIRR) in the Virtual Programmable Interrupt Controller (VPIC) of the specified DOS session for the IRQ specified. This causes an interrupt to be simulated to the DOS session.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  DOS session handle */
HIRQ    IRQHandle;  /*  Handle from VDHOpenVIRQ */
 
VDHSetVIRR(VDMHandle, IRQHandle);</pre>
 
 
 
 
=== VDHSetVIRR Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
 
 
 
 
=== VDHSetVIRR Parameter - IRQHandle ===
 
'''IRQHandle'''(HIRQ) IRQ handle from ''VDHOpenVIRQ''.
 
 
 
 
 
=== VDHSetVIRR - Return Value ===
 
Success If the function was successful, it returns nothing.
 
Failure If either of the parameters is invalid, a system halt occurs.
 
 
 
 
 
=== VDHSetVIRR - Parameters ===
 
'''VDMHandle'''(HVDM) DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
'''IRQHandle'''(HIRQ) IRQ handle from ''VDHOpenVIRQ''.
 
Success If the function was successful, it returns nothing.
 
Failure If either of the parameters is invalid, a system halt occurs.
 
 
 
 
 
=== VDHSetVIRR - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: If the interrupt request has not been cleared when the DOS session issues an End-Of-Interrupt (EOI), another interrupt will be simulated to the DOS session.
 
 
 
 
 
=== VDHSetVIRR - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetVPMExcept ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function sets the current value in the protected-mode exception table.
 
<pre class="western">#include mvdm.h
 
ULONG    Vector;          /*  Interrupt vector number */
FPFN    HandlerAddress;  /*  Far32 handler address */
BYTE    Flag;            /*  Flag indicating exception handler */
BOOL    rc;
 
rc = VDHSetVPMExcept(Vector, HandlerAddress,
      Flag);</pre>
 
 
 
 
=== VDHSetVPMExcept - Format ===
 
This function sets the current value in the protected-mode exception table.
 
<pre class="western">#include mvdm.h
 
ULONG    Vector;          /*  Interrupt vector number */
FPFN    HandlerAddress;  /*  Far32 handler address */
BYTE    Flag;            /*  Flag indicating exception handler */
BOOL    rc;
 
rc = VDHSetVPMExcept(Vector, HandlerAddress,
      Flag);</pre>
 
 
 
 
=== VDHSetVPMExcept Parameter - Vector ===
 
'''Vector'''(ULONG) Interrupt vector number.
 
 
 
 
 
=== VDHSetVPMExcept Parameter - HandlerAddress ===
 
'''HandlerAddress'''(FPFN) Far32 handler address.
 
 
 
 
 
=== VDHSetVPMExcept Parameter - Flag ===
 
'''Flag'''(BYTE) Flag indicating the kind of exception handler being registered.
 
Possible value:
 
VPMXCPT32 A 32-bit handler is being registered.
 
 
 
 
 
=== VDHSetVPMExcept Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHSetVPMExcept - Parameters ===
 
'''Vector'''(ULONG) Interrupt vector number.
 
'''HandlerAddress'''(FPFN) Far32 handler address.
 
'''Flag'''(BYTE) Flag indicating the kind of exception handler being registered.
 
Possible value:
 
VPMXCPT32 A 32-bit handler is being registered.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHSetVPMExcept - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: There must be a DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHSetVPMExcept - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetVPMIntVector ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function sets the application Ring 3 handler in the protected-mode interrupt chain. This is used only for DOS Protect Mode Interface (DPMI) support.
 
<pre class="western">#include mvdm.h
 
ULONG    Vector;          /*  Interrupt vector number */
FPFN    HandlerAddress;  /*  Far32 handler address */
BYTE    Flag;            /*  Flag. */
BOOL    rc;
 
rc = VDHSetVPMIntVector(Vector, HandlerAddress,
      Flag);</pre>
 
 
 
 
=== VDHSetVPMIntVector - Format ===
 
This function sets the application Ring 3 handler in the protected-mode interrupt chain. This is used only for DOS Protect Mode Interface (DPMI) support.
 
<pre class="western">#include mvdm.h
 
ULONG    Vector;          /*  Interrupt vector number */
FPFN    HandlerAddress;  /*  Far32 handler address */
BYTE    Flag;            /*  Flag. */
BOOL    rc;
 
rc = VDHSetVPMIntVector(Vector, HandlerAddress,
      Flag);</pre>
 
 
 
 
=== VDHSetVPMIntVector Parameter - Vector ===
 
'''Vector'''(ULONG) Interrupt vector number.
 
 
 
 
 
=== VDHSetVPMIntVector Parameter - HandlerAddress ===
 
'''HandlerAddress'''(FPFN) Far32 handler address.
 
 
 
 
 
=== VDHSetVPMIntVector Parameter - Flag ===
 
'''Flag'''(BYTE) Flag.
 
 
 
 
 
=== VDHSetVPMIntVector Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHSetVPMIntVector - Parameters ===
 
'''Vector'''(ULONG) Interrupt vector number.
 
'''HandlerAddress'''(FPFN) Far32 handler address.
 
'''Flag'''(BYTE) Flag.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHSetVPMIntVector - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: There must be a DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHSetVPMIntVector - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSwitchToVPM ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function switches the current DOS session into protected mode. This assumes that the appropriate initializations have already been performed.
 
<pre class="western">#include mvdm.h
 
VOID    ;
 
VDHSwitchToVPM();</pre>
 
 
 
 
=== VDHSwitchToVPM - Format ===
 
This function switches the current DOS session into protected mode. This assumes that the appropriate initializations have already been performed.
 
<pre class="western">#include mvdm.h
 
VOID    ;
 
VDHSwitchToVPM();</pre>
 
 
 
 
=== VDHSwitchToVPM Parameter - ===
 
None.
 
 
 
 
 
=== VDHSwitchToVPM - Return Value ===
 
None.
 
 
 
 
 
=== VDHSwitchToVPM - Parameters ===
 
None.
 
None.
 
 
 
 
 
=== VDHSwitchToVPM - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHSwitchToVPM - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSwitchToV86 ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function switches the current DOS session to V86 mode.
 
<pre class="western">#include mvdm.h
 
VOID    ;
 
VDHSwitchToV86();</pre>
 
 
 
 
=== VDHSwitchToV86 - Format ===
 
This function switches the current DOS session to V86 mode.
 
<pre class="western">#include mvdm.h
 
VOID    ;
 
VDHSwitchToV86();</pre>
 
 
 
 
=== VDHSwitchToV86 Parameter - ===
 
None.
 
 
 
 
 
=== VDHSwitchToV86 - Return Value ===
 
None.
 
 
 
 
 
=== VDHSwitchToV86 - Parameters ===
 
None.
 
None.
 
 
 
 
 
=== VDHSwitchToV86 - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHSwitchToV86 - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHThawVDM ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function reverses the effect of ''VDHFreezeVDM''. The specified DOS session is allowed to run when the freeze count becomes 0 (zero).
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Handle to the DOS session to thaw */
 
VDHThawVDM(VDMHandle);</pre>
 
 
 
 
=== VDHThawVDM - Format ===
 
This function reverses the effect of ''VDHFreezeVDM''. The specified DOS session is allowed to run when the freeze count becomes 0 (zero).
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Handle to the DOS session to thaw */
 
VDHThawVDM(VDMHandle);</pre>
 
 
 
 
=== VDHThawVDM Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session to allow to execute (thaw).
 
 
 
 
 
=== VDHThawVDM - Return Value ===
 
Success If the function is successful, it returns nothing. The freeze count for the DOS session is decremented.
 
Failure If ''VDMHandle''is an invalid handle, a system halt occurs.
 
 
 
 
 
=== VDHThawVDM - Parameters ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session to allow to execute (thaw).
 
Success If the function is successful, it returns nothing. The freeze count for the DOS session is decremented.
 
Failure If ''VDMHandle''is an invalid handle, a system halt occurs.
 
 
 
 
 
=== VDHThawVDM - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This function does nothing if called on behalf of a DOS session that is not frozen. See [[00477.htm|VDHFreezeVDM]]for a full discussion of freeze counting.
 
 
 
 
 
=== VDHThawVDM - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHUnlockMem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function reverses the effect of ''VDHLockMem'', unlocking a previously locked area of memory.
 
<pre class="western">#include mvdm.h
 
HLOCK    LockHandle;  /*  Lock handle from VDHLockMem */
 
VDHUnlockMem(LockHandle);</pre>
 
 
 
 
=== VDHUnlockMem - Format ===
 
This function reverses the effect of ''VDHLockMem'', unlocking a previously locked area of memory.
 
<pre class="western">#include mvdm.h
 
HLOCK    LockHandle;  /*  Lock handle from VDHLockMem */
 
VDHUnlockMem(LockHandle);</pre>
 
 
 
 
=== VDHUnlockMem Parameter - LockHandle ===
 
'''LockHandle'''(HLOCK) Lock handle of a locked memory area. Originally obtained from ''VDHLockMem''.
 
 
 
 
 
=== VDHUnlockMem - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure An invalid lock handle causes a system halt to occur.
 
 
 
 
 
=== VDHUnlockMem - Parameters ===
 
'''LockHandle'''(HLOCK) Lock handle of a locked memory area. Originally obtained from ''VDHLockMem''.
 
Success If the function is successful, it returns nothing.
 
Failure An invalid lock handle causes a system halt to occur.
 
 
 
 
 
=== VDHUnlockMem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Because lock handles are global, this function can be made in any task context.
 
 
 
 
 
=== VDHUnlockMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHUnreservePages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function unreserves pages that were previously reserved with ''VDHReservePages''. The starting address and size must be identical to the previous corresponding call to ''VDHReservePages''. Note that any mapping made earlier on this region is unmapped before calling this function.
 
<pre class="western">#include mvdm.h
 
PVOID    StartingAddress;  /*  Starting address of the region to unreserve */
ULONG    NumPages;        /*  Size of the region to unreserve, in pages */
 
VDHUnreservePages(StartingAddress, NumPages);</pre>
 
 
 
 
=== VDHUnreservePages - Format ===
 
This function unreserves pages that were previously reserved with ''VDHReservePages''. The starting address and size must be identical to the previous corresponding call to ''VDHReservePages''. Note that any mapping made earlier on this region is unmapped before calling this function.
 
<pre class="western">#include mvdm.h
 
PVOID    StartingAddress;  /*  Starting address of the region to unreserve */
ULONG    NumPages;        /*  Size of the region to unreserve, in pages */
 
VDHUnreservePages(StartingAddress, NumPages);</pre>
 
 
 
 
=== VDHUnreservePages Parameter - StartingAddress ===
 
'''StartingAddress'''(PVOID) Starting address of the region to unreserve. Must be less than 110000H (1MB+64KB) and must be page-aligned. In addition, ''StartingAddress''must match a previous ''VDHReservePages''call.
 
 
 
 
 
=== VDHUnreservePages Parameter - NumPages ===
 
'''NumPages'''(ULONG) Size, in pages, of the region to unreserve. Must match the corresponding parameter to a previous call to ''VDHReservePages''.
 
 
 
 
 
=== VDHUnreservePages - Return Value ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''StartingAddress''or ''NumPages''is invalid, or if they were not used together in an earlier call to ''VDHReservePages'', a system halt occurs.
 
 
 
 
 
=== VDHUnreservePages - Parameters ===
 
'''StartingAddress'''(PVOID) Starting address of the region to unreserve. Must be less than 110000H (1MB+64KB) and must be page-aligned. In addition, ''StartingAddress''must match a previous ''VDHReservePages''call.
 
'''NumPages'''(ULONG) Size, in pages, of the region to unreserve. Must match the corresponding parameter to a previous call to ''VDHReservePages''.
 
Success If the function is successful, it returns nothing.
 
Failure If ''StartingAddress''or ''NumPages''is invalid, or if they were not used together in an earlier call to ''VDHReservePages'', a system halt occurs.
 
 
 
 
 
=== VDHUnreservePages - Purpose ===
 
Context Issues: This function can be called in the initialization or DOS session-task context (DOS session creation). In the initialization context, memory can be unreserved only from the global linear memory map. In the DOS session-task context, memory can be unreserved only from the local linear memory map.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: ''StartingAddress''must be less than 110000H(1MB+64KB) and must be page -aligned. Additionally, ''StartingAddress''must match a previous call to ''VDHReservePages''. ''NumPages''must match the corresponding parameter to a previous call to ''VDHReservePages''.
 
 
 
 
 
=== VDHUnreservePages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHWaitEventSem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function is used to wait on an event semaphore. If the semaphore is posted, it will return immediately.
 
<pre class="western">#include mvdm.h
 
HVDHSEM    EventSemHandle;  /*  Event semaphore handle */
ULONG      Timeout;        /*  Timeout (in milliseconds) */
BOOL      rc;
 
rc = VDHWaitEventSem(EventSemHandle, Timeout);</pre>
 
 
 
 
=== VDHWaitEventSem - Format ===
 
This function is used to wait on an event semaphore. If the semaphore is posted, it will return immediately.
 
<pre class="western">#include mvdm.h
 
HVDHSEM    EventSemHandle;  /*  Event semaphore handle */
ULONG      Timeout;        /*  Timeout (in milliseconds) */
BOOL      rc;
 
rc = VDHWaitEventSem(EventSemHandle, Timeout);</pre>
 
 
 
 
=== VDHWaitEventSem Parameter - EventSemHandle ===
 
'''EventSemHandle'''(HVDHSEM) Event semaphore handle.
 
 
 
 
 
=== VDHWaitEventSem Parameter - Timeout ===
 
'''Timeout'''(ULONG) Number of milliseconds to wait before timing out.
 
 
 
 
 
=== VDHWaitEventSem Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns 1 (one).
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''EventSemHandle''is invalid , a system halt occurs.
 
 
 
 
 
=== VDHWaitEventSem - Parameters ===
 
'''EventSemHandle'''(HVDHSEM) Event semaphore handle.
 
'''Timeout'''(ULONG) Number of milliseconds to wait before timing out.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns 1 (one).
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''EventSemHandle''is invalid , a system halt occurs.
 
 
 
 
 
=== VDHWaitEventSem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function. If ''Timeout''is 0 (zero), the caller will not block; however, ERROR_TIMEOUT is returned. If ''Timeout''is -1, the caller is blocked until the semaphore is posted. Otherwise, the caller blocks for the time specified (in milliseconds) in ''Timeout''.
 
 
 
 
 
=== VDHWaitEventSem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHWaitVIRRs ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function waits until any virtual interrupt is simulated to the current DOS session.
 
<pre class="western">#include mvdm.h
 
HHOOK    PostInFcnHook;  /*  Hook handle */
BOOL    rc;
 
rc = VDHWaitVIRRs(PostInFcnHook);</pre>
 
 
 
 
=== VDHWaitVIRRs - Format ===
 
This function waits until any virtual interrupt is simulated to the current DOS session.
 
<pre class="western">#include mvdm.h
 
HHOOK    PostInFcnHook;  /*  Hook handle */
BOOL    rc;
 
rc = VDHWaitVIRRs(PostInFcnHook);</pre>
 
 
 
 
=== VDHWaitVIRRs Parameter - PostInFcnHook ===
 
'''PostInFcnHook'''(HHOOK) Hook handle of a routine that is to be called after interrupts are simulated.
 
 
 
 
 
=== VDHWaitVIRRs Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success The function returns a nonzero value, if it woke up because of a simulated interrupt. If it woke up because of a ''VDHWakeVIRRs''call, the function returns 0 (zero).
 
Failure If the function fails, it returns nothing.
 
 
 
 
 
=== VDHWaitVIRRs - Parameters ===
 
'''PostInFcnHook'''(HHOOK) Hook handle of a routine that is to be called after interrupts are simulated.
 
'''rc'''(BOOL) - returns
 
Success The function returns a nonzero value, if it woke up because of a simulated interrupt. If it woke up because of a ''VDHWakeVIRRs''call, the function returns 0 (zero).
 
Failure If the function fails, it returns nothing.
 
 
 
 
 
=== VDHWaitVIRRs - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: The hook handle must be allocated as a VDH_WAITVIRRS_HOOK type. This function is intended for virtual device drivers that need to simulate a spin loop without stopping virtual interrupt simulation. This allows the virtual device driver to be compatible with DOS but avoid wasting CPU time in a spin loop.
 
The DOS session's interrupts must be enabled, using ''VDHSetFlags'', before this service is used.
 
Generally, the virtual device driver will be in a loop when calling this function. When it returns a nonzero value, the virtual device driver returns to V86 mode so that the interrupt can be simulated. The hook function passed to this service is executed after all interrupts are simulated. When this function returns 0 (zero), it is because some other portion of the virtual device driver (likely in response to a physical hardware interrupt) has determined that the DOS session no longer needs to spin. The virtual device driver exits the loop at this point.
 
The virtual keyboard device driver behaves in this manner in order to emulate the ROM BIOS Read Keyboard function (INT 16H, AH=00) without using excessive CPU time, by allowing the ROM BIOS to spin out in V86 mode, or stopping simulated interrupts by performing a ''VDHWaitEventSem''.
 
 
 
 
 
=== VDHWaitVIRRs - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHWakeIdle ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function notes that the DOS session is busy (doing useful work). If the DOS session is currently sleeping or running at a lower priority because of the polling activities, the DOS session is awakened, its priority is restored, and it is no longer considered idle.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Handle to the DOS session to wake up */
 
VDHWakeIdle(VDMHandle);</pre>
 
 
 
 
=== VDHWakeIdle - Format ===
 
This function notes that the DOS session is busy (doing useful work). If the DOS session is currently sleeping or running at a lower priority because of the polling activities, the DOS session is awakened, its priority is restored, and it is no longer considered idle.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Handle to the DOS session to wake up */
 
VDHWakeIdle(VDMHandle);</pre>
 
 
 
 
=== VDHWakeIdle Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session to be awakened.
 
 
 
 
 
=== VDHWakeIdle - Return Value ===
 
None.
 
 
 
 
 
=== VDHWakeIdle - Parameters ===
 
'''VDMHandle'''(HVDM) Handle to the DOS session to be awakened.
 
None.
 
 
 
 
 
=== VDHWakeIdle - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHWakeIdle - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHWakeVIRRs ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function wakes up a DOS session that is waiting with the ''VDHWaitVIRRs''service. See [[01119.htm|VDHWaitVIRRs]]for a full description of the use of this function.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Handle of the DOS session to wake up */
 
VDHWakeVIRRs(VDMHandle);</pre>
 
 
 
 
=== VDHWakeVIRRs - Format ===
 
This function wakes up a DOS session that is waiting with the ''VDHWaitVIRRs''service. See [[01119.htm|VDHWaitVIRRs]]for a full description of the use of this function.
 
<pre class="western">#include mvdm.h
 
HVDM    VDMHandle;  /*  Handle of the DOS session to wake up */
 
VDHWakeVIRRs(VDMHandle);</pre>
 
 
 
 
=== VDHWakeVIRRs Parameter - VDMHandle ===
 
'''VDMHandle'''(HVDM) Handle of the DOS session to be awakened.
 
 
 
 
 
=== VDHWakeVIRRs - Return Value ===
 
Success If the function was successful, it returns nothing.
 
Failure If ''VDMHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHWakeVIRRs - Parameters ===
 
'''VDMHandle'''(HVDM) Handle of the DOS session to be awakened.
 
Success If the function was successful, it returns nothing.
 
Failure If ''VDMHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHWakeVIRRs - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Use with caution because it wakes up every virtual device driver that is waiting on a ''VDHWaitVIRRs''.
 
 
 
 
 
=== VDHWakeVIRRs - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHWrite ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function writes bytes to a file or device previously opened by ''VDHOpen'' .
 
<pre class="western">#include mvdm.h
 
HFILE    FileHandle;      /*  Handle to the file or device to write to */
PVOID    WriteBufferPtr;  /*  Pointer to the buffer to write */
ULONG    NumBytes;        /*  Number of bytes to write */
ULONG    rc;
 
rc = VDHWrite(FileHandle, WriteBufferPtr,
      NumBytes);</pre>
 
 
 
 
=== VDHWrite - Format ===
 
This function writes bytes to a file or device previously opened by ''VDHOpen'' .
 
<pre class="western">#include mvdm.h
 
HFILE    FileHandle;      /*  Handle to the file or device to write to */
PVOID    WriteBufferPtr;  /*  Pointer to the buffer to write */
ULONG    NumBytes;        /*  Number of bytes to write */
ULONG    rc;
 
rc = VDHWrite(FileHandle, WriteBufferPtr,
      NumBytes);</pre>
 
 
 
 
=== VDHWrite Parameter - FileHandle ===
 
'''FileHandle'''(HFILE) Handle to the file or device to write to.
 
 
 
 
 
=== VDHWrite Parameter - WriteBufferPtr ===
 
'''WriteBufferPtr'''(PVOID) Pointer to the buffer to write.
 
 
 
 
 
=== VDHWrite Parameter - NumBytes ===
 
'''NumBytes'''(ULONG) Number of bytes to write.
 
 
 
 
 
=== VDHWrite Return Value - rc ===
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns a count of the bytes written. This can be equal to 0 (zero).
 
Failure If the function fails, it returns 0FFFFFFFFH. ''VDHGetError''should be called to determine the nature of the problem. If ''FileHandle''is invalid, or this function is called in any context except DOS session-task, a system halt occurs.
 
 
 
 
 
=== VDHWrite - Parameters ===
 
'''FileHandle'''(HFILE) Handle to the file or device to write to.
 
'''WriteBufferPtr'''(PVOID) Pointer to the buffer to write.
 
'''NumBytes'''(ULONG) Number of bytes to write.
 
'''rc'''(ULONG) - returns
 
Success If the function is successful, it returns a count of the bytes written. This can be equal to 0 (zero).
 
Failure If the function fails, it returns 0FFFFFFFFH. ''VDHGetError''should be called to determine the nature of the problem. If ''FileHandle''is invalid, or this function is called in any context except DOS session-task, a system halt occurs.
 
 
 
 
 
=== VDHWrite - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHWrite - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHWriteUBuf ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function writes to protected-mode address space as if access were done at Ring 3. This means checking for supervisor and read-only faults, and trapping any other faults. All faults are passed on to the DOS session application handler through ''VDHRaiseException''.
 
<pre class="western">#include mvdm.h
 
PVOID    SourceBuffer;  /*  Source buffer from which to copy */
ULONG    ByteCount;      /*  Count of bytes */
SEL      Selector;      /*  Application selector */
PULONG    OffsetPointer;  /*  Address of the variable containing the offset */
ULONG    Flag;          /*  Flag for checking controls */
BOOL      rc;
 
rc = VDHWriteUBuf(SourceBuffer, ByteCount,
      Selector, OffsetPointer, Flag);</pre>
 
 
 
 
=== VDHWriteUBuf - Format ===
 
This function writes to protected-mode address space as if access were done at Ring 3. This means checking for supervisor and read-only faults, and trapping any other faults. All faults are passed on to the DOS session application handler through ''VDHRaiseException''.
 
<pre class="western">#include mvdm.h
 
PVOID    SourceBuffer;  /*  Source buffer from which to copy */
ULONG    ByteCount;      /*  Count of bytes */
SEL      Selector;      /*  Application selector */
PULONG    OffsetPointer;  /*  Address of the variable containing the offset */
ULONG    Flag;          /*  Flag for checking controls */
BOOL      rc;
 
rc = VDHWriteUBuf(SourceBuffer, ByteCount,
      Selector, OffsetPointer, Flag);</pre>
 
 
 
 
=== VDHWriteUBuf Parameter - SourceBuffer ===
 
'''SourceBuffer'''(PVOID) Source buffer from which to copy.
 
 
 
 
 
=== VDHWriteUBuf Parameter - ByteCount ===
 
'''ByteCount'''(ULONG) Count of bytes.
 
 
 
 
 
=== VDHWriteUBuf Parameter - Selector ===
 
'''Selector'''(SEL) Application selector.
 
 
 
 
 
=== VDHWriteUBuf Parameter - OffsetPointer ===
 
'''OffsetPointer'''(PULONG) Address of the variable containing the offset for the start of the write.
 
 
 
 
 
=== VDHWriteUBuf Parameter - Flag ===
 
'''Flag'''(ULONG) Checking control.
 
Possible values are:
 
VPM_PROT_READ Check for read. <br />VPM_PROT_WRITE Check for write. <br />VPM_FAULT_IF_SU_SET Fault, if supervisor pages. <br />VPM_FAULT_IF_RO Fault, if writing to read-only descriptor. <br />VPM_SEL_PRESENT Caller knows descriptor is present. <br />VPM_SEL_WRITEABLE Caller knows descriptor is writable. <br />VPM_SEL_IS_SS Selector is client's stack. <br />VPM_XCPTRET_ALT After exception, return to alternate mode. For example, if the client was in protected mode when the service was called, return in V86 mode after the exception is handled.
 
 
 
 
 
=== VDHWriteUBuf Return Value - rc ===
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero) if there is a bad address reference, which causes a fault. In such a case, ''OffsetPointer''is updated with the address of the fault. For Selector Faults, ''OffsetPointer''remains unchanged.
 
 
 
 
 
=== VDHWriteUBuf - Parameters ===
 
'''SourceBuffer'''(PVOID) Source buffer from which to copy.
 
'''ByteCount'''(ULONG) Count of bytes.
 
'''Selector'''(SEL) Application selector.
 
'''OffsetPointer'''(PULONG) Address of the variable containing the offset for the start of the write.
 
'''Flag'''(ULONG) Checking control.
 
Possible values are:
 
VPM_PROT_READ Check for read. <br />VPM_PROT_WRITE Check for write. <br />VPM_FAULT_IF_SU_SET Fault, if supervisor pages. <br />VPM_FAULT_IF_RO Fault, if writing to read-only descriptor. <br />VPM_SEL_PRESENT Caller knows descriptor is present. <br />VPM_SEL_WRITEABLE Caller knows descriptor is writable. <br />VPM_SEL_IS_SS Selector is client's stack. <br />VPM_XCPTRET_ALT After exception, return to alternate mode. For example, if the client was in protected mode when the service was called, return in V86 mode after the exception is handled.
 
'''rc'''(BOOL) - returns
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero) if there is a bad address reference, which causes a fault. In such a case, ''OffsetPointer''is updated with the address of the fault. For Selector Faults, ''OffsetPointer''remains unchanged.
 
 
 
 
 
=== VDHWriteUBuf - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: When the routine fails, the caller must clean up and exit so that the exception can be simulated to the user.
 
 
 
 
 
=== VDHWriteUBuf - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHYield ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
This function yields the processor to any other thread of equal or higher priority.
 
<pre class="western">#include mvdm.h
 
BOOL    OptionFlag;  /*  Yield options */
 
VDHYield(OptionFlag);</pre>
 
 
 
 
=== VDHYield - Format ===
 
This function yields the processor to any other thread of equal or higher priority.
 
<pre class="western">#include mvdm.h
 
BOOL    OptionFlag;  /*  Yield options */
 
VDHYield(OptionFlag);</pre>
 
 
 
 
=== VDHYield Parameter - OptionFlag ===
 
'''OptionFlag'''(BOOL) Yield options.
 
Possible value:
 
VDH_YIELD_TIME_CRITICAL Yield only to time-critical threads.
 
 
 
 
 
=== VDHYield - Return Value ===
 
None.
 
 
 
 
 
=== VDHYield - Parameters ===
 
'''OptionFlag'''(BOOL) Yield options.
 
Possible value:
 
VDH_YIELD_TIME_CRITICAL Yield only to time-critical threads.
 
None.
 
 
 
 
 
=== VDHYield - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: If ''OptionFlag''is VDH_YIELD_TIME_CRITICAL, and no time-critical thread is able to run, the caller keeps the CPU.
 
 
 
 
 
=== VDHYield - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=OS/2 Version Compatibility Considerations =
 
The following table lists information that has been added to or changed in this documentation since the availability of OS/2 Warp, Version 3. When writing a device driver, you will want to take into consideration these particular changes, which may affect the downward compatibility of these items.
The following table lists information that has been added to or changed in this documentation since the availability of OS/2 Warp, Version 3. When writing a device driver, you will want to take into consideration these particular changes, which may affect the downward compatibility of these items.
{|class="wikitable"
!Item Added or Changed ||Date Item Added or Changed||Compatibility of Addition or Change
|-
|Advanced OS/2 Joystick Device Driver||November 1995||OS/2 Warp, Version 3 and higher
|}


<pre class="western">
[[Category:Device Driver Reference]]
/--------------------------------------------------------------\
|Item Added or      |Date Item Added or  |Compatibility of    |
|Changed            |Changed            |Addition or Change  |
|--------------------+--------------------+--------------------|
|Advanced OS/2      |November 1995      |OS/2 Warp, Version 3|
|Joystick Device    |                    |and higher          |
|Driver              |                    |                    |
\--------------------------------------------------------------/
</pre>
 
= Assembler Language Syntax =
 
This appendix categorizes the assembler language versions of all virtual DevHlp services in following list and in subsequent sections. These APIs are counterparts of the C language services listed in [[00129.htm|C Language Virtual DevHlp Services]].
 
A detailed description of each function follows the [[01169.htm|Virtual DevHlp Services by Category]].
 
Function Type <br />[[01190.htm|VDHAllocBlock]]byte-granular memory management service <br />
[[01197.htm|VDHAllocDMABuffer]]DMA service <br />
[[01206.htm|VDHAllocDOSMem]]byte-granular memory management service <br />
[[01213.htm|VDHAllocHook]]hook management service <br />
[[01222.htm|VDHAllocMem]]byte-granular memory management service <br />[[01230.htm|VDHAllocPages]]page-granular memory management service <br />[[01239.htm|VDHArmBPHook]]hook management service <br />[[01246.htm|VDHArmContextHook]]hook management service <br />[[01254.htm|VDHArmReturnHook]]hook management service <br />[[01262.htm|VDHArmSTIHook]]hook management service <br />[[01270.htm|VDHArmTimerHook]]timer service <br />[[01279.htm|VDHArmVPMBPHook]]DPMI service <br />[[01286.htm|VDHBeginUseVPMStack]]DPMI service <br />[[01293.htm|VDHCallOutDMA]]DMA service <br />[[01300.htm|VDHChangeVPMIF]]DPMI service <br />[[01307.htm|VDHCheckPagePerm]]DPMI service <br />[[01317.htm|VDHCheckVPMIntVector]]DPMI service <br />[[01324.htm|VDHClearVIRR]]virtual interrupt service <br />[[01332.htm|VDHClose]]file or device I/O service <br />[[01339.htm|VDHCloseVDD]]inter-device communication service <br />[[01346.htm|VDHCloseVIRQ]]virtual interrupt service <br />[[01353.htm|VDHCopyMem]]byte-granular memory management service <br />[[01362.htm|VDHCreateBlockPool]]byte-granular memory management service <br />[[01370.htm|VDHCreateSel]]GDT selector service <br />[[01378.htm|VDHCreateSem]]semaphore service <br />[[01386.htm|VDHDecodeProperty]]DOS settings service <br />[[01396.htm|VDHDestroyBlockPool]]byte-granular memory management service <br />[[01403.htm|VDHDestroySel]]GDT selector service <br />[[01410.htm|VDHDestroySem]]semaphore service <br />[[01417.htm|VDHDevBeep]]miscellaneous virtual DevHlp service <br />[[01425.htm|VDHDevIOCtl]]file or device I/O service <br />[[01440.htm|VDHDisarmTimerHook]]timer service <br />[[01447.htm|VDHEndUseVPMStack]]DPMI service <br />[[01454.htm|VDHEnumerateVDMs]]miscellaneous virtual DevHlp service <br />[[01462.htm|VDHExchangeMem]]byte-granular memory management service <br />[[01471.htm|VDHFindFreePages]]page-granular memory management service <br />[[01479.htm|VDHFreeBlock]]byte-granular memory management service <br />[[01487.htm|VDHFreeDMABuffer]]DMA service <br />[[01494.htm|VDHFreeHook]]hook management service <br />[[01501.htm|VDHFreeMem]]byte-granular memory management service <br />[[01508.htm|VDHFreePages]]page-granular memory management service <br />[[01515.htm|VDHFreezeVDM]]DOS session control service <br />[[01522.htm|VDHGetCodePageFont]]miscellaneous virtual DevHlp service <br />[[01531.htm|VDHGetDirtyPageInfo]]page-granular memory management service <br />[[01540.htm|VDHGetError]]miscellaneous virtual DevHlp service <br />[[01547.htm|VDHGetFlags]]miscellaneous virtual DevHlp service <br />[[01554.htm|VDHGetSelBase]]DPMI service <br />[[01562.htm|VDHGetVPMExcept]]DPMI service <br />[[01571.htm|VDHGetVPMIntVector]]DPMI service <br />[[01579.htm|VDHHaltSystem]]DOS session control service <br />[[01586.htm|VDHHandleFromPID]]miscellaneous virtual DevHlp service <br />[[01593.htm|VDHHandleFromSGID]]miscellaneous virtual DevHlp service <br />[[01600.htm|VDHInstallFaultHook]]page-granular memory management service <br />[[01611.htm|VDHInstallIntHook]]hook management service <br />[[01621.htm|VDHInstallIOHook]]hook management service <br />[[01632.htm|VDHInstallUserHook]]hook management service <br />[[01640.htm|VDHIsVDMFrozen]]DOS session control service <br />[[01647.htm|VDHKillVDM]]DOS session control service <br />[[01654.htm|VDHLockMem]]memory-locking memory management service <br />[[01665.htm|VDHMapPages]]page-granular memory management service <br />[[01674.htm|VDHOpen]]file or device I/O service <br />[[01688.htm|VDHOpenPDD]]inter-device communication service <br />[[01696.htm|VDHOpenVDD]]inter-device communication service <br />[[01703.htm|VDHOpenVIRQ]]virtual interrupt service <br />[[01714.htm|VDHPhysicalDisk]]file or device I/O service <br />[[01725.htm|VDHPopInt]]v8086 stack manipulation service <br />[[01732.htm|VDHPopRegs]]v8086 stack manipulation service <br />[[01739.htm|VDHPopStack]]v8086 stack manipulation service <br />[[01747.htm|VDHPopup]]miscellaneous virtual DevHlp service <br />[[01759.htm|VDHPostEventSem]]semaphore service <br />[[01766.htm|VDHPrintClose]]parallel port and printer service <br />[[01773.htm|VDHPushFarCall]]v8086 stack manipulation service <br />[[01780.htm|VDHPushInt]]v8086 stack manipulation service <br />[[01787.htm|VDHPushRegs]]v8086 stack manipulation service <br />[[01794.htm|VDHPushStack]]v8086 stack manipulation service <br />[[01802.htm|VDHPutSysValue]]miscellaneous virtual DevHlp service <br />[[01810.htm|VDHQueryFreePages]]page-granular memory management service <br />[[01817.htm|VDHQueryHookData]]hook management service <br />[[01824.htm|VDHQueryLin]]miscellaneous virtual DevHlp service <br />[[01831.htm|VDHQueryKeyShift]]keyboard service <br />[[01838.htm|VDHQueryProperty]]DOS settings service <br />[[01845.htm|VDHQuerySel]]GDT selector service <br />[[01852.htm|VDHQuerySem]]semaphore service <br />[[01860.htm|VDHQuerySysValue]]miscellaneous virtual DevHlp service <br />[[01868.htm|VDHQueryVIRQ]]virtual interrupt service <br />[[01876.htm|VDHRaiseException]]DPMI service <br />[[01885.htm|VDHRead]]file or device I/O service <br />[[01894.htm|VDHReadUBuf]]DPMI service <br />[[01905.htm|VDHReallocPages]]page-granular memory management service <br />[[01914.htm|VDHRegisterAPI]]Register API handler <br />[[01923.htm|VDHRegisterDMAChannel]]DMA service <br />[[01931.htm|VDHRegisterProperty]]DOS settings service <br />[[01946.htm|VDHRegisterVDD]]inter-device communication service <br />[[01955.htm|VDHReleaseCodePageFont]]miscellaneous virtual DevHlp service <br />[[01962.htm|VDHReleaseMutexSem]]semaphore service <br />[[01969.htm|VDHRemoveFaultHook]]page-granular memory management service <br />[[01979.htm|VDHRemoveIOHook]]hook management service <br />[[01989.htm|VDHReportPeek]]idle DOS application management service <br />[[01996.htm|VDHRequestMutexSem]]semaphore service <br />[[02004.htm|VDHRequestVDD]]inter-device communication service <br />[[02015.htm|VDHReservePages]]page-granular memory management service <br />[[02023.htm|VDHResetEventSem]]semaphore service <br />[[02030.htm|VDHSeek]]file or device I/O service <br />[[02039.htm|VDHSendVEOI]]virtual interrupt service <br />[[02046.htm|VDHSetDosDevice]]miscellaneous virtual DevHlp service <br />[[02053.htm|VDHSetError]]miscellaneous virtual DevHlp service <br />[[02060.htm|VDHSetFlags]]miscellaneous virtual DevHlp service <br />[[02067.htm|VDHSetIOHookState]]hook management service <br />[[02078.htm|VDHSetPriority]]DOS session control service <br />[[02087.htm|VDHSetVIRR]]virtual interrupt service <br />[[02095.htm|VDHSetVPMExcept]]DPMI service <br />[[02104.htm|VDHSetVPMIntVector]]DPMI service <br />[[02113.htm|VDHSwitchToVPM]]DPMI service <br />[[02120.htm|VDHSwitchToV86]]DPMI service <br />[[02127.htm|VDHThawVDM]]DOS session control service <br />[[02134.htm|VDHUnlockMem]]memory-locking memory management service <br />[[02141.htm|VDHUnreservePages]]page-granular memory management service <br />[[02149.htm|VDHWaitEventSem]]semaphore service <br />[[02157.htm|VDHWaitVIRRs]]virtual interrupt service <br />[[02164.htm|VDHWakeIdle]]idle DOS application management service <br />[[02171.htm|VDHWakeVIRRs]]virtual interrupt service <br />[[02178.htm|VDHWrite]]file or device I/O service <br />[[02187.htm|VDHWriteUBuf]]DPMI service <br />[[02198.htm|VDHYield]]DOS session control service
 
== Virtual DevHlp Services by Category ==
 
Virtual DevHlp services can be divided into categories based on the type of service the virtual DevHlp provides. These categories are:
 
 
 
 
 
=== DMA Services ===
 
Function Type <br />[[01197.htm|VDHAllocDMABuffer]]Allocate DMA buffer <br />[[01293.htm|VDHCallOutDMA]]Call virtual DMA device driver <br />[[01487.htm|VDHFreeDMABuffer]]Free DMA buffer <br />[[01923.htm|VDHRegisterDMAChannel]]Register DMA channel
 
 
 
 
 
=== DOS Session Control Services ===
 
Function Type <br />[[01515.htm|VDHFreezeVDM]]Freeze DOS session <br />[[01579.htm|VDHHaltSystem]]Cause system halt <br />[[01640.htm|VDHIsVDMFrozen]]Determine if DOS session is frozen <br />[[01647.htm|VDHKillVDM]]Terminate DOS session <br />[[02078.htm|VDHSetPriority]]Adjust DOS session scheduler priority <br />[[02127.htm|VDHThawVDM]]Allow frozen DOS session to resume executing <br />[[02198.htm|VDHYield]]Yield the processor.
 
 
 
 
 
=== DOS Settings Services ===
 
Function Type <br />[[01386.htm|VDHDecodeProperty]]Decode property string <br />[[01838.htm|VDHQueryProperty]]Query virtual device driver property value <br />[[01931.htm|VDHRegisterProperty]]Register virtual device driver property
 
 
 
 
 
=== DPMI Services ===
 
Function Type <br />[[01279.htm|VDHArmVPMBPHook]]Obtain address of DOS session protected-mode breakpoint <br />[[01286.htm|VDHBeginUseVPMStack]]Begin using DOS session protected-mode stack <br />[[01300.htm|VDHChangeVPMIF]]Change virtual Interrupt Flag (IF) <br />[[01307.htm|VDHCheckPagePerm]]Check Ring 3 page permissions <br />[[01317.htm|VDHCheckVPMIntVector]]Determine if DOS session protected-mode handler exists <br />[[01447.htm|VDHEndUseVPMStack]]End use of DOS session protected-mode stack <br />[[01554.htm|VDHGetSelBase]]Get flat base address <br />[[01562.htm|VDHGetVPMExcept]]Get DOS session protected-mode exception vector <br />[[01571.htm|VDHGetVPMIntVector]]Return DOS session protected-mode interrupt vector <br />[[01876.htm|VDHRaiseException]]Raise an exception to a DOS session <br />[[01894.htm|VDHReadUBuf]]Read from protected-mode address space <br />[[02095.htm|VDHSetVPMExcept]]Set DOS session protected-mode exception vector <br />[[02104.htm|VDHSetVPMIntVector]]Set DOS session protected-mode interrupt vector <br />[[02113.htm|VDHSwitchToVPM]]Switch DOS session to protected mode <br />[[02120.htm|VDHSwitchToV86]]Switch DOS session to V86 mode <br />[[02187.htm|VDHWriteUBuf]]Write to protected-mode address space
 
'''Note:'''&quot;VPM&quot;, as found in the function names above, stands for ''Virtual Protected Mode''.
 
 
 
 
 
=== File or Device I/O Services ===
 
Function Type <br />[[01332.htm|VDHClose]]Close a file handle <br />[[01425.htm|VDHDevIOCtl]]Issue device-specific commands <br />[[01674.htm|VDHOpen]]Open a file or device <br />[[01714.htm|VDHPhysicalDisk]]Get information about partitionable disks <br />[[01885.htm|VDHRead]]Read bytes from file or device <br />[[02030.htm|VDHSeek]]Move read or write file pointer for a handle <br />[[02178.htm|VDHWrite]]Write bytes to file or device
 
 
 
 
 
=== GDT Selector Services ===
 
Function Type <br />[[01370.htm|VDHCreateSel]]Create GDT selector to map a linear range <br />[[01403.htm|VDHDestroySel]]Destroy GDT selector <br />[[01845.htm|VDHQuerySel]]Get selector for data or stack address
 
 
 
 
 
=== Hook Management Services ===
 
Function Type <br />[[01213.htm|VDHAllocHook]]Allocate hooks needed for interrupt simulation <br />[[01239.htm|VDHArmBPHook]]Obtain address of V86 breakpoint <br />[[01246.htm|VDHArmContextHook]]Set local or global context hook <br />[[01254.htm|VDHArmReturnHook]]Set handler to receive control <br />[[01262.htm|VDHArmSTIHook]]Set handler to receive control <br />[[01494.htm|VDHFreeHook]]Disarm and free hook <br />[[01611.htm|VDHInstallIntHook]]Set handler for V86 interrupt <br />[[01621.htm|VDHInstallIOHook]]Install I/O port hooks <br />[[01632.htm|VDHInstallUserHook]]Install handler for DOS session event <br />[[01817.htm|VDHQueryHookData]]Returns pointer to hook reference data <br />[[01979.htm|VDHRemoveIOHook]]Remove hooks for PIC I/O ports <br />[[02067.htm|VDHSetIOHookState]]Enable/disable I/O port trapping
 
 
 
 
 
=== Idle DOS Application Management Services ===
 
Function Type <br />[[01989.htm|VDHReportPeek]]Report DOS session polling activity <br />[[02164.htm|VDHWakeIdle]]Wake up DOS session
 
'''Note:'''The services above indicate when a DOS application appears to be idle, and when activity exists that could make the DOS application ''busy''.
 
 
 
 
 
=== Inter-Device Communication Services ===
 
DevHlp services
 
Function Type <br />[[01339.htm|VDHCloseVDD]]Close virtual device driver <br />[[01688.htm|VDHOpenPDD]]Open physical device driver <br />[[01696.htm|VDHOpenVDD]]Open virtual device driver <br />[[01946.htm|VDHRegisterVDD]]Register virtual device driver entry points <br />[[02004.htm|VDHRequestVDD]]Issue request for virtual device driver operation
 
 
 
 
 
=== Keyboard Services ===
 
Function Type <br />[[01831.htm|VDHQueryKeyShift]]Query keyboard shift state
 
 
 
 
 
=== Memory Management Services ===
 
There are three sub-categories of the memory management virtual DevHlp services. The first two are used for the granularity of the memory allocation unit, the third category is used for memory-locking services.
 
 
 
 
 
=== Byte-Granular Memory Management Services ===
 
Function Type <br />[[01190.htm|VDHAllocBlock]]Allocate block from memory block pool <br />[[01206.htm|VDHAllocDOSMem]]Allocate block of memory from DOS area <br />[[01222.htm|VDHAllocMem]]Allocate small amount of memory <br />[[01353.htm|VDHCopyMem]]Copy from one linear memory address to another <br />[[01362.htm|VDHCreateBlockPool]]Create memory block pool <br />[[01396.htm|VDHDestroyBlockPool]]Destroy memory block pool <br />[[01462.htm|VDHExchangeMem]]Exchange contents of two linear memory regions <br />[[01479.htm|VDHFreeBlock]]Free block of memory <br />[[01501.htm|VDHFreeMem]]Free memory
 
 
 
 
 
=== Page-Granular Memory Management Services ===
 
Function Type <br />[[01230.htm|VDHAllocPages]]Allocate page-aligned memory object <br />[[01471.htm|VDHFindFreePages]]Find largest available linear memory <br />[[01508.htm|VDHFreePages]]Free memory object <br />[[01531.htm|VDHGetDirtyPageInfo]]Return status of dirty bits <br />[[01600.htm|VDHInstallFaultHook]]Install page fault handler <br />[[01665.htm|VDHMapPages]]Map specified linear address <br />[[01810.htm|VDHQueryFreePages]]Return amount of free virtual memory <br />[[01905.htm|VDHReallocPages]]Reallocate memory object <br />[[01969.htm|VDHRemoveFaultHook]]Remove page fault handler <br />[[02015.htm|VDHReservePages]]Reserve range of linear addresses <br />[[02141.htm|VDHUnreservePages]]Unreserve range of linear addresses
 
 
 
 
 
=== Memory-Locking Memory Management Services ===
 
Function Type <br />[[01654.htm|VDHLockMem]]Verify access or lock memory <br />[[02134.htm|VDHUnlockMem]]Release memory lock
 
'''Note:'''The services above allow virtual device drivers to allocate, free, reallocate, and lock memory for global, per-DOS session, page-granular, or byte-granular objects.
 
Four types of mappings are supported:
 
*Mapping to a physical address <br />*Mapping to another linear address <br />*Mapping to black holes (don't care) pages <br />*Mapping to invalid (unmapped) pages
 
'''Note:'''Virtual device drivers can also request smaller memory allocations from the kernel heap, which is global and fixed. Small, fixed size block services are available to speed up frequent allocations and freeing of memory. For a particular block size, a pool of blocks is maintained and the requirements are met by taking off a block from the block pool.
 
 
 
 
 
=== Miscellaneous Virtual DevHlp Services ===
 
Function Type <br />[[01417.htm|VDHDevBeep]]Device beep virtual DevHlp service <br />[[01454.htm|VDHEnumerateVDMs]]Run worker function for each DOS session <br />[[01522.htm|VDHGetCodePageFont]]Return information of DOS session code page font <br />[[01540.htm|VDHGetError]]Get error code from last virtual DevHlp service <br />[[01547.htm|VDHGetFlags]]Get DOS Session's EFLAGS Register <br />[[01586.htm|VDHHandleFromPID]]Get handle for given Process ID <br />[[01593.htm|VDHHandleFromSGID]]Get DOS session handle from Screen Group ID <br />[[01747.htm|VDHPopup]]Display message <br />[[01802.htm|VDHPutSysValue]]Set system value <br />[[01824.htm|VDHQueryLin]]Get linear address for Far16 address <br />[[01860.htm|VDHQuerySysValue]]Query system value <br />[[01914.htm|VDHRegisterAPI]]Register API handler <br />[[01955.htm|VDHReleaseCodePageFont]]Release code page font <br />[[02046.htm|VDHSetDosDevice]]Register/install DOS device driver <br />[[02053.htm|VDHSetError]]Set error code <br />[[02060.htm|VDHSetFlags]]Set DOS session flags register
 
 
 
 
 
=== Parallel Port and Printer Services ===
 
Function Type <br />[[01766.htm|VDHPrintClose]]Flush and close open printers for DOS session
 
 
 
 
 
=== Semaphore Services ===
 
Function Type <br />[[01378.htm|VDHCreateSem]]Create event or mutex semaphore <br />[[01410.htm|VDHDestroySem]]Destroy semaphore <br />[[01759.htm|VDHPostEventSem]]Post event semaphore <br />[[01852.htm|VDHQuerySem]]Query semaphore state <br />[[01962.htm|VDHReleaseMutexSem]]Release mutex semaphore <br />[[01996.htm|VDHRequestMutexSem]]Request mutex semaphore <br />[[02023.htm|VDHResetEventSem]]Reset event semaphore <br />[[02149.htm|VDHWaitEventSem]]Wait on event semaphore
 
'''Note:'''These semaphore services above are used for synchronizing with an OS /2 process. Virtual device drivers must be careful not to block ( VDHRequestMutexSem/VDHWaitEventSem) in the context of a DOS session task; otherwise, that task will receive no more simulated hardware interrupts until it becomes unblocked.
 
 
 
 
 
=== Timer Services ===
 
Function Type <br />[[01270.htm|VDHArmTimerHook]]Set timer service/handler <br />[[01440.htm|VDHDisarmTimerHook]]Cancel timer service
 
 
 
 
 
=== Virtual Interrupt Services ===
 
Function Type <br />[[01324.htm|VDHClearVIRR]]Clear virtual IRR <br />[[01346.htm|VDHCloseVIRQ]]Deregister IRQ handler <br />[[01703.htm|VDHOpenVIRQ]]Register IRQ handler <br />[[01868.htm|VDHQueryVIRQ]]Query IRQ status on a DOS session <br />[[02039.htm|VDHSendVEOI]]Send virtual EOI to VPIC <br />[[02087.htm|VDHSetVIRR]]Set virtual interrupt request register (IRR) <br />[[02157.htm|VDHWaitVIRRs]]Wait until interrupt is simulated <br />[[02171.htm|VDHWakeVIRRs]]Wake up DOS session
 
 
 
 
 
=== V8086 Stack Manipulation Services ===
 
Function Type <br />[[01725.htm|VDHPopInt]]Remove IRET frame from client DOS session stack <br />[[01732.htm|VDHPopRegs]]Pop client DOS session registers from client stack <br />[[01739.htm|VDHPopStack]]Pop data off client stack <br />[[01773.htm|VDHPushFarCall]]Simulate FAR call to V86 code <br />[[01780.htm|VDHPushInt]]Transfer control to V86 interrupt handler <br />[[01787.htm|VDHPushRegs]]Push client DOS session registers onto client stack <br />[[01794.htm|VDHPushStack]]Push data onto client stack
 
 
 
 
 
== VDHAllocBlock ==
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
This function allocates a block from the specified
memory block pool.  This block is allocated from fixed or
swappable memory, depending on the value
of the OptionFlag flag when the block
is created with VDHCreateBlockPool.
*/
 
include mvdm.inc
 
EXTERN  VDHAllocBlock:NEAR
SourceBlockPool  DD ?    ;  Handle to a memory block pool
 
PUSH    SourceBlockPool  ;  Push SourceBlockPool
 
CALL    VDHAllocBlock        ; Call the function</pre>
 
 
 
 
=== VDHAllocBlock - Format ===
 
 
 
<pre class="western">/*
This function allocates a block from the specified
memory block pool.  This block is allocated from fixed or
swappable memory, depending on the value
of the OptionFlag flag when the block
is created with VDHCreateBlockPool.
*/
 
include mvdm.inc
 
EXTERN  VDHAllocBlock:NEAR
SourceBlockPool  DD ?    ;  Handle to a memory block pool
 
PUSH    SourceBlockPool  ;  Push SourceBlockPool
 
CALL    VDHAllocBlock        ; Call the function</pre>
 
 
 
 
=== VDHAllocBlock Parameter - SourceBlockPool ===
 
'''SourceBlockPool'''(DD) Handle to the pool of memory blocks from which to allocate a memory block.
 
 
 
 
 
=== VDHAllocBlock Return Value - rc ===
 
Success If the function is successful, it returns the address of the allocated memory block.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. Note that passing an invalid memory block handle causes a system halt to occur.
 
 
 
 
 
=== VDHAllocBlock - Parameters ===
 
'''SourceBlockPool'''(DD) Handle to the pool of memory blocks from which to allocate a memory block.
 
 
 
 
 
=== VDHAllocBlock - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: Any blocks allocated by a virtual device driver for use by the terminating DOS session are freed by using ''VDHFreeBlock''. Any block pools created for the DOS session should also be freed.
 
 
 
 
 
=== VDHAllocBlock - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
== VDHAllocDMABuffer ==
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  allocates  a  DMA  buffer .
* /
 
include  mvdm . inc
 
EXTERN    VDHAllocDMABuffer : NEAR
RequestSize    DD  ?      ;    Request  size
Align64kFlag    DD  ?      ;    Alignment  flag
PhysAddrPtr    DD  ?      ;    Location  to  store  the  physical  address  returned
 
PUSH      RequestSize    ;    Push  RequestSize
PUSH      Align64kFlag    ;    Push  Align64kFlag
PUSH      PhysAddrPtr    ;    Push  PhysAddrPtr
 
CALL      VDHAllocDMABuffer      ;  Call  the  function </pre>
 
 
 
 
=== VDHAllocDMABuffer - Format ===
 
 
 
<pre class="western">/*
 
This  function  allocates  a  DMA  buffer .
* /
 
include  mvdm . inc
 
EXTERN    VDHAllocDMABuffer : NEAR
RequestSize    DD  ?      ;    Request  size
Align64kFlag    DD  ?      ;    Alignment  flag
PhysAddrPtr    DD  ?      ;    Location  to  store  the  physical  address  returned
 
PUSH      RequestSize    ;    Push  RequestSize
PUSH      Align64kFlag    ;    Push  Align64kFlag
PUSH      PhysAddrPtr    ;    Push  PhysAddrPtr
 
CALL      VDHAllocDMABuffer      ;  Call  the  function </pre>
 
 
 
 
=== VDHAllocDMABuffer Parameter - RequestSize ===
 
'''RequestSize'''(DD) Request Size.
 
If the ''Align64kFlag''=1, ''RequestSize''is always less than or equal to 64KB. If the ''Align64kFlag''=0, ''RequestSize''is always less than or equal to 128KB.
 
 
 
 
 
=== VDHAllocDMABuffer Parameter - Align64kFlag ===
 
'''Align64kFlag'''(DD) Alignment flag.
 
If ''Align64kFlag''=1, the buffer is at a 64KB alignment in physical memory. If ''Align64kFlag''=0, the buffer is at a 128KB alignment in physical memory.
 
 
 
 
 
=== VDHAllocDMABuffer Parameter - PhysAddrPtr ===
 
'''PhysAddrPtr'''(DD) Location where ''VDHAllocDMABuffer''returns the physical address of the allocation.
 
 
 
 
 
=== VDHAllocDMABuffer Return Value - rc ===
 
Success If the function is successful, it returns the linear address of allocation (system memory).
 
Failure If the function fails, it returns -1. ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHAllocDMABuffer - Parameters ===
 
'''RequestSize'''(DD) Request Size.
 
If the ''Align64kFlag''=1, ''RequestSize''is always less than or equal to 64KB. If the ''Align64kFlag''=0, ''RequestSize''is always less than or equal to 128KB.
 
'''Align64kFlag'''(DD) Alignment flag.
 
If ''Align64kFlag''=1, the buffer is at a 64KB alignment in physical memory. If ''Align64kFlag''=0, the buffer is at a 128KB alignment in physical memory.
 
'''PhysAddrPtr'''(DD) Location where ''VDHAllocDMABuffer''returns the physical address of the allocation.
 
 
 
 
 
=== VDHAllocDMABuffer - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: The virtual device driver frees the buffer by using ''VDHFreeDMABuffer''at DOS session termination.
 
Notes: Physical memory is allocated resident and contiguous, and is always in the first 16MB. The Linear Memory range comes from the system arena. The contents of the returned buffer are not important; that is, the buffer is not zero-filled.
 
 
 
 
 
=== VDHAllocDMABuffer - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
== VDHAllocDOSMem ==
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  allocates  a  block  of  memory  from  the  DOS  memory  area .
Allocations  start  at  0  bytes  and  go  to  256KB .
* /
 
include  mvdm . inc
 
EXTERN    VDHAllocDOSMem : NEAR
BlockSize    DD  ?      ;    Size  of  the  desired  memory  block  ( in  bytes )
 
PUSH      BlockSize    ;    Push  BlockSize
 
CALL      VDHAllocDOSMem    ;  Call  the  function </pre>
 
 
 
 
=== VDHAllocDOSMem - Format ===
 
 
 
<pre class="western">/*
 
This  function  allocates  a  block  of  memory  from  the  DOS  memory  area .
Allocations  start  at  0  bytes  and  go  to  256KB .
* /
 
include  mvdm . inc
 
EXTERN    VDHAllocDOSMem : NEAR
BlockSize    DD  ?      ;    Size  of  the  desired  memory  block  ( in  bytes )
 
PUSH      BlockSize    ;    Push  BlockSize
 
CALL      VDHAllocDOSMem    ;  Call  the  function </pre>
 
 
 
 
=== VDHAllocDOSMem Parameter - BlockSize ===
 
'''BlockSize'''(DD) Size of the desired memory block; the number of bytes to allocate.
 
 
 
 
 
=== VDHAllocDOSMem Return Value - rc ===
 
Success If the function is successful, it returns the address of the allocated memory block.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. If ''BlockSize''= 0, or if the function is called in an invalid context (see &quot;Context Issues&quot; below), a system halt occurs.
 
 
 
 
 
=== VDHAllocDOSMem - Parameters ===
 
'''BlockSize'''(DD) Size of the desired memory block; the number of bytes to allocate.
 
 
 
 
 
=== VDHAllocDOSMem - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context (DOS session creation).
 
DOS Session Terminations: There are no DOS session termination implications for this function. The DOS Session Manager frees this memory.
 
Notes: There is no way to free memory taken from the DOS heap. If there is no free memory in the DOS memory area, the allocation fails. Allocations always start on paragraph (16-byte) boundaries.
 
 
 
 
 
=== VDHAllocDOSMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
== VDHAllocHook ==
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  to  allocate  a  hook  handle  for  the  arm
hook  services :
Context ,  STI ,  Return ,  Timer ,  and  BP  ( breakpoint ) .
* /
 
include  mvdm . inc
 
EXTERN    VDHAllocHook : NEAR
HookType      DD  ?      ;    Hook  type
ArmHookFcn    DD  ?      ;    Arm  hook  function
RefDataSize    DD  ?      ;    Size  of  the  reference  data
 
PUSH      HookType      ;    Push  HookType
PUSH      ArmHookFcn    ;    Push  ArmHookFcn
PUSH      RefDataSize    ;    Push  RefDataSize
 
CALL      VDHAllocHook      ;  Call  the  function </pre>
 
 
 
 
=== VDHAllocHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  to  allocate  a  hook  handle  for  the  arm
hook  services :
Context ,  STI ,  Return ,  Timer ,  and  BP  ( breakpoint ) .
* /
 
include  mvdm . inc
 
EXTERN    VDHAllocHook : NEAR
HookType      DD  ?      ;    Hook  type
ArmHookFcn    DD  ?      ;    Arm  hook  function
RefDataSize    DD  ?      ;    Size  of  the  reference  data
 
PUSH      HookType      ;    Push  HookType
PUSH      ArmHookFcn    ;    Push  ArmHookFcn
PUSH      RefDataSize    ;    Push  RefDataSize
 
CALL      VDHAllocHook      ;  Call  the  function </pre>
 
 
 
 
=== VDHAllocHook Parameter - HookType ===
 
'''HookType'''(DD) Hook type.
 
Possible values are:
 
VDH_CONTEXT_HOOK VDHArmContextHook <br />VDH_STI_HOOK VDHArmSTIHook <br />VDH_RETURN_HOOK VDHArmReturnHook <br />VDH_TIMER_HOOK VDHArmTimerHook <br />VDH_BP_HOOK VDHArmBPHook
 
 
 
 
 
=== VDHAllocHook Parameter - ArmHookFcn ===
 
'''ArmHookFcn'''(DD) Arm hook function.
 
 
 
 
 
=== VDHAllocHook Parameter - RefDataSize ===
 
'''RefDataSize'''(DD) Size of the reference data.
 
 
 
 
 
=== VDHAllocHook Return Value - rc ===
 
Success If the function is successful, it returns a hook handle, which is used in the Arm services.
 
Failure If there is an error, the function returns NULL. ''VDHGetError''should be called to determine the nature of the problem. If ''HookType''or ''ArmHookFcn''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHAllocHook - Parameters ===
 
'''HookType'''(DD) Hook type.
 
Possible values are:
 
VDH_CONTEXT_HOOK VDHArmContextHook <br />VDH_STI_HOOK VDHArmSTIHook <br />VDH_RETURN_HOOK VDHArmReturnHook <br />VDH_TIMER_HOOK VDHArmTimerHook <br />VDH_BP_HOOK VDHArmBPHook
 
'''ArmHookFcn'''(DD) Arm hook function.
 
'''RefDataSize'''(DD) Size of the reference data.
 
 
 
 
 
=== VDHAllocHook - Purpose ===
 
Context Issues: This function can be called in the initialization or DOS session-task context. However, VDH_RETURN_HOOK and VDH_BP_HOOK require the DOS session-task context.
 
DOS Session Terminations: During initialization time, hooks are allocated globally; that is, they are not associated with a DOS session process. These hooks are not automatically freed when a DOS session terminates. During DOS session creation time or thereafter, allocated hooks are associated with the current DOS session, and are freed when that DOS session terminates.
 
Notes: Use ''VDHQueryHookData''to get a pointer to any reference data allocated.
 
 
 
 
 
=== VDHAllocHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
== VDHAllocMem ==
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  allocates  a  small  amount  of  memory  on  a  LONG / DWORD  boundary .
The  memory  is  allocated  from  the  system  area ,  so  the  address
is  valid  in  all  process  contexts .
* /
 
include  mvdm . inc
 
EXTERN    VDHAllocMem : NEAR
NumBytes      DD  ?
OptionFlag    DD  ?      ;    Number  of  bytes  to  allocate
 
PUSH      NumBytes      ;    Push  NumBytes
PUSH      OptionFlag    ;    Push  OptionFlag
 
CALL      VDHAllocMem    ;  Call  the  function </pre>
 
 
 
 
=== VDHAllocMem - Format ===
 
 
 
<pre class="western">/*
 
This  function  allocates  a  small  amount  of  memory  on  a  LONG / DWORD  boundary .
The  memory  is  allocated  from  the  system  area ,  so  the  address
is  valid  in  all  process  contexts .
* /
 
include  mvdm . inc
 
EXTERN    VDHAllocMem : NEAR
NumBytes      DD  ?
OptionFlag    DD  ?      ;    Number  of  bytes  to  allocate
 
PUSH      NumBytes      ;    Push  NumBytes
PUSH      OptionFlag    ;    Push  OptionFlag
 
CALL      VDHAllocMem    ;  Call  the  function </pre>
 
 
 
 
=== VDHAllocMem Parameter - NumBytes ===
 
'''NumBytes'''(DD) Number of bytes to allocate.
 
 
 
 
 
=== VDHAllocMem Parameter - OptionFlag ===
 
'''OptionFlag'''(DD) Bit flag describing the allocation options.
 
Possible value:
 
VDHAM_SWAPPABLE Allocate memory from the swappable heap. Otherwise, memory is allocated from the fixed heap and can be accessed at hardware interrupt time.
 
 
 
 
 
=== VDHAllocMem Return Value - rc ===
 
Success If the function is successful, it returns the address of the allocated space.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. If either ''NumBytes''or ''OptionFlag''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHAllocMem - Parameters ===
 
'''NumBytes'''(DD) Number of bytes to allocate.
 
'''OptionFlag'''(DD) Bit flag describing the allocation options.
 
Possible value:
 
VDHAM_SWAPPABLE Allocate memory from the swappable heap. Otherwise, memory is allocated from the fixed heap and can be accessed at hardware interrupt time.
 
 
 
 
 
=== VDHAllocMem - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: All memory allocated by a virtual device driver for use by the terminating DOS session is freed by using ''VDHFreeMem''.
 
Notes: Allocations larger than one page are performed by using ''VDHAllocPages''. To access the allocated memory at hardware interrupt time, be sure to allocate memory from the fixed heap.
 
 
 
 
 
=== VDHAllocMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHAllocPages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  allocates  a  page - aligned ,  page - granular  memory  object .
* /
 
include  mvdm . inc
 
EXTERN    VDHAllocPages : NEAR
StartingAddress    DD  ?      ;    A  specific  linear  address
NumPages          DD  ?      ;    The  number  of  pages  to  allocate
OptionFlag        DD  ?      ;    Allocation  options  bit - flag
 
PUSH      StartingAddress    ;    Push  StartingAddress
PUSH      NumPages          ;    Push  NumPages
PUSH      OptionFlag        ;    Push  OptionFlag
 
CALL      VDHAllocPages          ;  Call  the  function </pre>
 
 
 
 
=== VDHAllocPages - Format ===
 
 
 
<pre class="western">/*
 
This  function  allocates  a  page - aligned ,  page - granular  memory  object .
* /
 
include  mvdm . inc
 
EXTERN    VDHAllocPages : NEAR
StartingAddress    DD  ?      ;    A  specific  linear  address
NumPages          DD  ?      ;    The  number  of  pages  to  allocate
OptionFlag        DD  ?      ;    Allocation  options  bit - flag
 
PUSH      StartingAddress    ;    Push  StartingAddress
PUSH      NumPages          ;    Push  NumPages
PUSH      OptionFlag        ;    Push  OptionFlag
 
CALL      VDHAllocPages          ;  Call  the  function </pre>
 
 
 
 
=== VDHAllocPages Parameter - StartingAddress ===
 
'''StartingAddress'''(DD) A specific address used with the available options ( see ''Option Flag'').
 
 
 
 
 
=== VDHAllocPages Parameter - NumPages ===
 
'''NumPages'''(DD) Number of pages of linear memory to allocate.
 
 
 
 
 
=== VDHAllocPages Parameter - OptionFlag ===
 
'''OptionFlag'''(DD) Bit flag indicating choices in allocation options.
 
This flag can take one or more of the following values:
 
VDHAP_SPECIFIC ''VDHAllocPages''attempts to allocate pages starting at the linear address, ''StartingAddress''. Otherwise, an arbitrary linear address is selected.
 
VDHAP_SYSTEM The linear address is allocated from the system (global) area, essentially allocating global memory. Otherwise, it is allocated from the private area of this process.
 
VDHAP_FIXED The allocated memory is fixed. Otherwise, the memory is swappable. This flag cannot be used if VDHAP_PHYSICAL is specified.
 
VDHAP_PHYSICAL The allocated linear address range maps the physical address range, starting at ''StartingAddress''. Otherwise, an arbitrary physical page is assigned. Note that this flag cannot be used if VDHAP_FIXED is specified .
 
 
 
 
 
=== VDHAllocPages Return Value - rc ===
 
Success If the function is successful, it returns the address of the allocated memory.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. If the ''OptionFlag''flag is invalid, a system halt occurs.
 
 
 
 
 
=== VDHAllocPages - Parameters ===
 
'''StartingAddress'''(DD) A specific address used with the available options ( see ''Option Flag'').
 
'''NumPages'''(DD) Number of pages of linear memory to allocate.
 
'''OptionFlag'''(DD) Bit flag indicating choices in allocation options.
 
This flag can take one or more of the following values:
 
VDHAP_SPECIFIC ''VDHAllocPages''attempts to allocate pages starting at the linear address, ''StartingAddress''. Otherwise, an arbitrary linear address is selected.
 
VDHAP_SYSTEM The linear address is allocated from the system (global) area, essentially allocating global memory. Otherwise, it is allocated from the private area of this process.
 
VDHAP_FIXED The allocated memory is fixed. Otherwise, the memory is swappable. This flag cannot be used if VDHAP_PHYSICAL is specified.
 
VDHAP_PHYSICAL The allocated linear address range maps the physical address range, starting at ''StartingAddress''. Otherwise, an arbitrary physical page is assigned. Note that this flag cannot be used if VDHAP_FIXED is specified .
 
 
 
 
 
=== VDHAllocPages - Purpose ===
 
Context Issues: This function can be called in the initialization or task context. If called in the initialization context, VDHAP_SYSTEM must be specified. If called in the OS/2 task context, VDHAP_SYSTEM must also be specified.
 
DOS Session Terminations: Any allocations that are not in the terminating DOS sessions private area must be released by using ''VDHFreePages''.
 
Notes: When an allocation made with ''VDHAllocPages''is shrunk by ''VDHReallocPages'', the linear range between the end of the allocation and the original end of the allocation remains available for object growth without movement. Regardless of ''VDHReallocPages''activity, all pages in the allocation retain the same properties (that is fixed, system, and physical) .
 
 
 
 
 
=== VDHAllocPages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHArmBPHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  obtains  the  address  of  the  V86  breakpoint  allocated  by
a  previous  call  to
VDHAllocHook  with  the  VDH _ BP _ HOOK  flag .
* /
 
include  mvdm . inc
 
EXTERN    VDHArmBPHook : NEAR
HookHandle    DD  ?      ;    Hook  handle
 
PUSH      HookHandle    ;    Push  HookHandle
 
CALL      VDHArmBPHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHArmBPHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  obtains  the  address  of  the  V86  breakpoint  allocated  by
a  previous  call  to
VDHAllocHook  with  the  VDH _ BP _ HOOK  flag .
* /
 
include  mvdm . inc
 
EXTERN    VDHArmBPHook : NEAR
HookHandle    DD  ?      ;    Hook  handle
 
PUSH      HookHandle    ;    Push  HookHandle
 
CALL      VDHArmBPHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHArmBPHook Parameter - HookHandle ===
 
'''HookHandle'''(DD) Hook handle allocated with ''VDHAllocHook''.
 
Hook routine interface:
 
<pre class="western">HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - p    - Pointer to hook-specific reference data
;          [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT  None
;
; CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHArmBPHook Return Value - rc ===
 
Success If the function is successful, it returns a V86 breakpoint address.
 
Failure If ''HookHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHArmBPHook - Parameters ===
 
'''HookHandle'''(DD) Hook handle allocated with ''VDHAllocHook''.
 
Hook routine interface:
 
<pre class="western">HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - p    - Pointer to hook-specific reference data
;          [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT  None
;
; CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHArmBPHook - Purpose ===
 
Context Issues: This function can be called only in the task context, and needs to be called only at DOS session creation time.
 
DOS Session Terminations: There are no DOS session termination implications for this function. BP (breakpoint) hooks are automatically removed during DOS session termination.
 
Notes: This VDH service provides a raw breakpoint service. Upon entry to the arm hook function, the client's CS:IP is randomly set. Therefore, it is crucial that this function set the CS:IP to a valid address. Typically, the CS:IP is retrieved from the client's stack through use of ''VDHPopStack''. This is a low-level service. Appropriate care should be exercised to ensure that the client's CS:IP and stack remain valid.
 
Unlike other hooks, breakpoint hooks are armed until explicitly disarmed by a call to ''VDHFreeHook''. When the V86 breakpoint address is called from V86 mode, the hook function is called. Any changes made to the client register frame cause the corresponding registers to take on these values upon return to V86 mode. The ''p''parameter in the hook routine points to the ''cbRefData''bytes of data allocated by ''VDHAllocHook''.
 
 
 
 
 
=== VDHArmBPHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHArmContextHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  to  get  to  a  task - time  context  from
interrupt  time  when  an  interrupt  is  simulated .
This  service  adds  a
handler  to  the  list  of  routines  called  the  next  time  the  task  context
is  entered  ( global  context ) ,  or  the  next  time  a  specific  DOS  session - task
context  is  reached  ( local  context ) .
This  is  done  only  once ;  the  handler
is  removed  from  the  list  after  it  is  executed .
* /
 
include  mvdm . inc
 
EXTERN    VDHArmContextHook : NEAR
HookHandle    DD  ?      ;    Hook  handle  allocated  with  VDHAllocHook
VDMHandle    DD  ?      ;    DOS  session  handle
 
PUSH      HookHandle    ;    Push  HookHandle
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHArmContextHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHArmContextHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  to  get  to  a  task - time  context  from
interrupt  time  when  an  interrupt  is  simulated .
This  service  adds  a
handler  to  the  list  of  routines  called  the  next  time  the  task  context
is  entered  ( global  context ) ,  or  the  next  time  a  specific  DOS  session - task
context  is  reached  ( local  context ) .
This  is  done  only  once ;  the  handler
is  removed  from  the  list  after  it  is  executed .
* /
 
include  mvdm . inc
 
EXTERN    VDHArmContextHook : NEAR
HookHandle    DD  ?      ;    Hook  handle  allocated  with  VDHAllocHook
VDMHandle    DD  ?      ;    DOS  session  handle
 
PUSH      HookHandle    ;    Push  HookHandle
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHArmContextHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHArmContextHook Parameter - HookHandle ===
 
'''HookHandle'''(DD) Hook handle allocated with ''VDHAllocHook''.
 
 
 
 
 
=== VDHArmContextHook Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) DOS session handle. A value of -1 indicates a global context .
 
Hook routine interface:
 
<pre class="western">HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;          [ESP + 4] - pcrf    - Pointer to client register frame
;    EXIT  None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  Task (global) or DOS session-task (local)
; NOTE      pcrf is valid only for local context hook handlers</pre>
 
 
 
 
 
 
=== VDHArmContextHook Return Value - rc ===
 
Success If the function was successful, it returns nothing.
 
Failure If ''HookHandle''or ''VDMHandle''is invalid, or if the hook is already armed, a system halt occurs.
 
 
 
 
 
=== VDHArmContextHook - Parameters ===
 
'''HookHandle'''(DD) Hook handle allocated with ''VDHAllocHook''.
 
'''VDMHandle'''(DD) DOS session handle. A value of -1 indicates a global context .
 
Hook routine interface:
 
<pre class="western">HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;          [ESP + 4] - pcrf    - Pointer to client register frame
;    EXIT  None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  Task (global) or DOS session-task (local)
; NOTE      pcrf is valid only for local context hook handlers</pre>
 
 
 
 
 
 
=== VDHArmContextHook - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: Any context hooks allocated in the context of the terminating DOS session are deallocated by the DOS Session Manager.
 
Notes: After calling this routine, the caller is guaranteed that the context hook will be executed before any user-space code (global context) or any V86 code in the specified DOS session (local context).
 
 
 
 
 
=== VDHArmContextHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHArmReturnHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  sets  a  service  to  receive  control  when  an  Interrupt
Return  ( IRET )  or  Far  Return  ( RETF )  instruction  is  executed  in  V86
mode  or  when  VDHPopInt  is  executed .
* /
 
include  mvdm . inc
 
EXTERN    VDHArmReturnHook : NEAR
HookHandle    DD  ?      ;    Hook  handle
RetHookType    DD  ?      ;    Return  hook  type
 
PUSH      HookHandle    ;    Push  HookHandle
PUSH      RetHookType    ;    Push  RetHookType
 
CALL      VDHArmReturnHook      ;  Call  the  function </pre>
 
 
 
 
=== VDHArmReturnHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  sets  a  service  to  receive  control  when  an  Interrupt
Return  ( IRET )  or  Far  Return  ( RETF )  instruction  is  executed  in  V86
mode  or  when  VDHPopInt  is  executed .
* /
 
include  mvdm . inc
 
EXTERN    VDHArmReturnHook : NEAR
HookHandle    DD  ?      ;    Hook  handle
RetHookType    DD  ?      ;    Return  hook  type
 
PUSH      HookHandle    ;    Push  HookHandle
PUSH      RetHookType    ;    Push  RetHookType
 
CALL      VDHArmReturnHook      ;  Call  the  function </pre>
 
 
 
 
=== VDHArmReturnHook Parameter - HookHandle ===
 
'''HookHandle'''(DD) Hook handles the routine to get control on an IRET/RETF. Allocated with ''VDHAllocHook''.
 
 
 
 
 
=== VDHArmReturnHook Parameter - RetHookType ===
 
'''RetHookType'''(DD) Return hook type.
 
Possible values are:
 
VDHARH_NORMAL_IRET <br />VDHARH_NORMAL_RET <br />VDHARH_RECURSIVE_IRET <br />VDHARH_RECURSIVE_RET <br />VDHARH_CSEIP_HOOK <br />VDHARH_RECURSIVE_CSEIP_HOOK
 
Hook routine interface:
 
<pre class="western">HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;          [ESP + 4] - pcrf    - Pointer to client register frame
;    EXIT  None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHArmReturnHook Return Value - rc ===
 
Success If the function was successful it returns a nonzero value.
 
Failure If VDHARH_NORMAL_x is already armed, the function returns 0. If ''HookHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHArmReturnHook - Parameters ===
 
'''HookHandle'''(DD) Hook handles the routine to get control on an IRET/RETF. Allocated with ''VDHAllocHook''.
 
'''RetHookType'''(DD) Return hook type.
 
Possible values are:
 
VDHARH_NORMAL_IRET <br />VDHARH_NORMAL_RET <br />VDHARH_RECURSIVE_IRET <br />VDHARH_RECURSIVE_RET <br />VDHARH_CSEIP_HOOK <br />VDHARH_RECURSIVE_CSEIP_HOOK
 
Hook routine interface:
 
<pre class="western">HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;          [ESP + 4] - pcrf    - Pointer to client register frame
;    EXIT  None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHArmReturnHook - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: Any return hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager.
 
Notes: The VDHARH_NORMAL_RET and VDHARH_RECURSIVE_RET return hook types can be made only after ''VDHPushFarCall''has been called, but before returning to V86 mode. The return hook types, VDHARH_NORMAL_IRET and VDHARH_RECURSIVE_ IRET, can be made only in the following contexts:
 
*Within a software interrupt handler set by ''VDHInstallIntHook''<br />*After ''VDHPushInt''has been called, but before returning to V86 mode
 
The VDHARH_RECURSIVE_x return types push two extra WORDs on the client's stack before the IRET or RET frame. VDHARH_CSEIP_HOOK and VDHARH_RECURSIVE_ CSEIP_HOOK are meant to be used before a ''VDHPushInt''or ''VDHPushFarCall'', as it is more efficient to do this type of return hook first. Only the normal and recursive CS:EIP hooks will work in DOS session protected mode.
 
 
 
 
 
=== VDHArmReturnHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHArmSTIHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  sets  a  handler  to  receive  control  when  the  current
DOS  session  enables  simulated  interrupts .
This  handler  is  called  only  once .
If  interrupts  are  already  enabled  in  the  DOS  session ,  the  handler  is  called
immediately .
* /
 
include  mvdm . inc
 
EXTERN    VDHArmSTIHook : NEAR
HookHandle    DD  ?      ;    Hook  handle  allocated  with  VDHAllocHook
VDMHandle    DD  ?      ;    DOS  session  handle
 
PUSH      HookHandle    ;    Push  HookHandle
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHArmSTIHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHArmSTIHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  sets  a  handler  to  receive  control  when  the  current
DOS  session  enables  simulated  interrupts .
This  handler  is  called  only  once .
If  interrupts  are  already  enabled  in  the  DOS  session ,  the  handler  is  called
immediately .
* /
 
include  mvdm . inc
 
EXTERN    VDHArmSTIHook : NEAR
HookHandle    DD  ?      ;    Hook  handle  allocated  with  VDHAllocHook
VDMHandle    DD  ?      ;    DOS  session  handle
 
PUSH      HookHandle    ;    Push  HookHandle
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHArmSTIHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHArmSTIHook Parameter - HookHandle ===
 
'''HookHandle'''(DD) Hook handle allocated with ''VDHAllocHook''.
 
 
 
 
 
=== VDHArmSTIHook Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) DOS session handle.
 
Hook routine interface:
 
<pre class="western">HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;          [ESP + 4] - pcrf    - Pointer to client register frame
;    EXIT  None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHArmSTIHook Return Value - rc ===
 
Success If the function was successful, it returns nothing.
 
Failure If either ''HookHandle''or ''VDMHandle''is invalid, or if the hook is already armed, a system halt occurs.
 
 
 
 
 
=== VDHArmSTIHook - Parameters ===
 
'''HookHandle'''(DD) Hook handle allocated with ''VDHAllocHook''.
 
'''VDMHandle'''(DD) DOS session handle.
 
Hook routine interface:
 
<pre class="western">HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;          [ESP + 4] - pcrf    - Pointer to client register frame
;    EXIT  None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHArmSTIHook - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: Any STI hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager.
 
Notes: Interrupt re-enabling detection is performed when the DOS session runs with IOPL = 0. This causes any instructions that might modify the interrupt flag to fault.
 
 
 
 
 
=== VDHArmSTIHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHArmTimerHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  sets  a  timer  handler  to  be  called  after  a  specified
period  of  time  has  elapsed .
The  handler  is  called  only  once .
* /
 
include  mvdm . inc
 
EXTERN    VDHArmTimerHook : NEAR
HookHandle    DD  ?      ;    Timer  hook  handle
Duration      DD  ?      ;    Duration  of  the  timeout  in  milliseconds
VDMHandle    DD  ?      ;    DOS  session  handle
 
PUSH      HookHandle    ;    Push  HookHandle
PUSH      Duration      ;    Push  Duration
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHArmTimerHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHArmTimerHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  sets  a  timer  handler  to  be  called  after  a  specified
period  of  time  has  elapsed .
The  handler  is  called  only  once .
* /
 
include  mvdm . inc
 
EXTERN    VDHArmTimerHook : NEAR
HookHandle    DD  ?      ;    Timer  hook  handle
Duration      DD  ?      ;    Duration  of  the  timeout  in  milliseconds
VDMHandle    DD  ?      ;    DOS  session  handle
 
PUSH      HookHandle    ;    Push  HookHandle
PUSH      Duration      ;    Push  Duration
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHArmTimerHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHArmTimerHook Parameter - HookHandle ===
 
'''HookHandle'''(DD) Timer hook handle.
 
 
 
 
 
=== VDHArmTimerHook Parameter - Duration ===
 
'''Duration'''(DD) Timer duration in milliseconds.
 
 
 
 
 
=== VDHArmTimerHook Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) DOS session handle.
 
Possible values are:
 
DOS Session Handle or 0 When the specified time duration expires, a local context hook is automatically armed by using the specified ''HookHandle''.
 
VDH_TIMER_GLOBAL_CONTEXT When the specified time duration expires, a global context hook is automatically armed by using the specified ''HookHandle''.
 
VDH_TIMER_INTERRUPT_HOOK When the specified time duration expires, the timer hook specified by ''HookHandle''is called at interrupt time.
 
Hook routine interface:
 
<pre class="western">HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pRefData - Pointer to reference data
;    EXIT  None
;
; CONTEXT  Interrupt</pre>
 
 
 
 
 
 
=== VDHArmTimerHook Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If either ''Duration''or ''HookHandle''is invalid or the hook is already armed, a system halt occurs.
 
 
 
 
 
=== VDHArmTimerHook - Parameters ===
 
'''HookHandle'''(DD) Timer hook handle.
 
'''Duration'''(DD) Timer duration in milliseconds.
 
'''VDMHandle'''(DD) DOS session handle.
 
Possible values are:
 
DOS Session Handle or 0 When the specified time duration expires, a local context hook is automatically armed by using the specified ''HookHandle''.
 
VDH_TIMER_GLOBAL_CONTEXT When the specified time duration expires, a global context hook is automatically armed by using the specified ''HookHandle''.
 
VDH_TIMER_INTERRUPT_HOOK When the specified time duration expires, the timer hook specified by ''HookHandle''is called at interrupt time.
 
Hook routine interface:
 
<pre class="western">HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pRefData - Pointer to reference data
;    EXIT  None
;
; CONTEXT  Interrupt</pre>
 
 
 
 
 
 
=== VDHArmTimerHook - Purpose ===
 
Context Issues: This function can be called in the initialization, task, or interrupt context.
 
DOS Session Terminations: Any timer hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager at DOS session termination.
 
Notes: If type VDH_TIMER_INTERRUPT_HOOK, the timer handler cannot block since it executes at physical interrupt time.
 
 
 
 
 
=== VDHArmTimerHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHArmVPMBPHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  obtains  the  address  of  the  DOS  session ' s
protected - mode  breakpoint
allocated  by  a  previous  call  to  VDHAllocHook  with
the  VDH _ BP _ HOOK  flag .
* /
 
include  mvdm . inc
 
EXTERN    VDHArmVPMBPHook : NEAR
HookHandle    DD  ?      ;    Hook  handle  allocated  with  VDHAllocHook
 
PUSH      HookHandle    ;    Push  HookHandle
 
CALL      VDHArmVPMBPHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHArmVPMBPHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  obtains  the  address  of  the  DOS  session ' s
protected - mode  breakpoint
allocated  by  a  previous  call  to  VDHAllocHook  with
the  VDH _ BP _ HOOK  flag .
* /
 
include  mvdm . inc
 
EXTERN    VDHArmVPMBPHook : NEAR
HookHandle    DD  ?      ;    Hook  handle  allocated  with  VDHAllocHook
 
PUSH      HookHandle    ;    Push  HookHandle
 
CALL      VDHArmVPMBPHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHArmVPMBPHook Parameter - HookHandle ===
 
'''HookHandle'''(DD) Hook handle allocated with ''VDHAllocHook''.
 
The hook routine interface:
 
<pre class="western">HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to hook-specific reference data
;          [ESP + 4] - pcrf - Pointer to client register frame
;
;    EXIT  None
;
; CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHArmVPMBPHook Return Value - rc ===
 
Success If the function is successful, it returns a DOS session protected- mode breakpoint address.
 
Failure If ''HookHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHArmVPMBPHook - Parameters ===
 
'''HookHandle'''(DD) Hook handle allocated with ''VDHAllocHook''.
 
The hook routine interface:
 
<pre class="western">HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to hook-specific reference data
;          [ESP + 4] - pcrf - Pointer to client register frame
;
;    EXIT  None
;
; CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHArmVPMBPHook - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Unlike other hooks, breakpoint hooks are armed until explicitly disarmed by a call to ''VDHFreeHook''. When the breakpoint address is executed from DOS session protected mode, the hook function is called. Any changes made to the client register frame cause the corresponding registers to take on these values after returning to the DOS session. The ''p''parameter in the hook routine points to the ''RefDataSize''bytes of data allocated by ''VDHAllocHook''.
 
''VDHArmVPMBPHook''provides a raw breakpoint service. On entry to the arm hook function, the client's CS:EIP is randomly set. It is therefore crucial that the virtual device driver's hook handler sets the CS:EIP to a valid address . Typically, the CS:EIP is retrieved from the client's stack through the use of ''VDHPopStack'', which is a low-level service. Appropriate care should be exercised to ensure that the client's CS:EIP and stack remain valid.
 
The breakpoint address returned will be valid for all DPMI clients within the DOS session. The breakpoint address may be placed in the DPMI application's IDT (see [[01066.htm|VDHSetVPMIntVector]]), but will have to be rehooked each time a DPMI task starts (see [[00594.htm|VDHInstallUserHook]]).
 
There must be a protected-mode DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHArmVPMBPHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHBeginUseVPMStack ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  to  switch  to  the  DOS  session ' s  protected - mode
stack  for  hardware  interrupts ,  exceptions ,  and  so  forth .
This  service
can  be  called  repeatedly ,  but  only  the  first  call  will  switch  stacks .
Subsequent  calls  increment  use ,  count  but  remain  on  the  VPM  stack .
* /
 
include  mvdm . inc
 
EXTERN    VDHBeginUseVPMStack : NEAR
                DD  ?
 
PUSH                      ;    Push
 
CALL      VDHBeginUseVPMStack      ;  Call  the  function </pre>
 
 
 
 
=== VDHBeginUseVPMStack - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  to  switch  to  the  DOS  session ' s  protected - mode
stack  for  hardware  interrupts ,  exceptions ,  and  so  forth .
This  service
can  be  called  repeatedly ,  but  only  the  first  call  will  switch  stacks .
Subsequent  calls  increment  use ,  count  but  remain  on  the  VPM  stack .
* /
 
include  mvdm . inc
 
EXTERN    VDHBeginUseVPMStack : NEAR
                DD  ?
 
PUSH                      ;    Push
 
CALL      VDHBeginUseVPMStack      ;  Call  the  function </pre>
 
 
 
 
=== VDHBeginUseVPMStack Parameter - ===
 
(DD) None.
 
 
 
 
 
=== VDHBeginUseVPMStack Return Value - ===
 
None.
 
 
 
 
 
=== VDHBeginUseVPMStack - Parameters ===
 
(DD) None.
 
 
 
 
 
=== VDHBeginUseVPMStack - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: There must be a DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHBeginUseVPMStack - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCallOutDMA ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  by  the
virtual  DMA  device  driver  ( VDMA )  to  check  how  much  DMA  transfer  has
been  completed ,  and  to  copy  the  contents  from  the  temporary  buffer  to
the  DOS  area .
 
If  a  virtual  device  driver  owns  a  DMA  channel ,  it  must  call
the  virtual  DMA  device  driver  for  those  interrupts  that  occur  when  a
DMA  request  is  pending  on  that  channel .
This  service  also  indicates  when  the  DOS  session  is  done  with
the  channel  so  that  the  channel  can  be  given  to  another  waiting  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHCallOutDMA : NEAR
                DD  ?
 
PUSH                      ;    Push
 
CALL      VDHCallOutDMA      ;  Call  the  function </pre>
 
 
 
 
=== VDHCallOutDMA - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  by  the
virtual  DMA  device  driver  ( VDMA )  to  check  how  much  DMA  transfer  has
been  completed ,  and  to  copy  the  contents  from  the  temporary  buffer  to
the  DOS  area .
 
If  a  virtual  device  driver  owns  a  DMA  channel ,  it  must  call
the  virtual  DMA  device  driver  for  those  interrupts  that  occur  when  a
DMA  request  is  pending  on  that  channel .
This  service  also  indicates  when  the  DOS  session  is  done  with
the  channel  so  that  the  channel  can  be  given  to  another  waiting  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHCallOutDMA : NEAR
                DD  ?
 
PUSH                      ;    Push
 
CALL      VDHCallOutDMA      ;  Call  the  function </pre>
 
 
 
 
=== VDHCallOutDMA Parameter - ===
 
(DD) None.
 
 
 
 
 
=== VDHCallOutDMA Return Value - ===
 
None.
 
 
 
 
 
=== VDHCallOutDMA - Parameters ===
 
(DD) None.
 
 
 
 
 
=== VDHCallOutDMA - Purpose ===
 
Context Issues: This function can be called in any context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHCallOutDMA - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHChangeVPMIF ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  changes  the  virtual  Interrupt  Flag  ( IF )  that  enables
or  disables  protected - mode  interrupts .
This  change  is  reflected  in  a  bit
in  the
flVDMStatus  kernel  variable  ( see  &quot; Notes &quot;  under  Purpose ) .
If  the  STI
hooks  are  waiting  and  interrupts  are  enabled ,  the  hooks  are  called .
* /
 
include  mvdm . inc
 
EXTERN    VDHChangeVPMIF : NEAR
SetIFFlag    DD  ?      ;    Indicates  whether  to  turn  the  IF  flag  on  or  off
 
PUSH      SetIFFlag    ;    Push  SetIFFlag
 
CALL      VDHChangeVPMIF    ;  Call  the  function </pre>
 
 
 
 
=== VDHChangeVPMIF - Format ===
 
 
 
<pre class="western">/*
 
This  function  changes  the  virtual  Interrupt  Flag  ( IF )  that  enables
or  disables  protected - mode  interrupts .
This  change  is  reflected  in  a  bit
in  the
flVDMStatus  kernel  variable  ( see  &quot; Notes &quot;  under  Purpose ) .
If  the  STI
hooks  are  waiting  and  interrupts  are  enabled ,  the  hooks  are  called .
* /
 
include  mvdm . inc
 
EXTERN    VDHChangeVPMIF : NEAR
SetIFFlag    DD  ?      ;    Indicates  whether  to  turn  the  IF  flag  on  or  off
 
PUSH      SetIFFlag    ;    Push  SetIFFlag
 
CALL      VDHChangeVPMIF    ;  Call  the  function </pre>
 
 
 
 
=== VDHChangeVPMIF Parameter - SetIFFlag ===
 
'''SetIFFlag'''(DD) Indicates whether to turn the IF flag ON or OFF. If nonzero, set IF flag to 1 (one). If zero, set IF flag to 0 (zero).
 
 
 
 
 
=== VDHChangeVPMIF Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure Not applicable to this function.
 
 
 
 
 
=== VDHChangeVPMIF - Parameters ===
 
'''SetIFFlag'''(DD) Indicates whether to turn the IF flag ON or OFF. If nonzero, set IF flag to 1 (one). If zero, set IF flag to 0 (zero).
 
 
 
 
 
=== VDHChangeVPMIF - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: The ''flVDMStatus''kernel variable is exported from the kernel. Any virtual device driver can refer to it directly. ''flVDMStatus''is a DD-sized variable that contains various DOS session status flags relating to protected mode and the DOS Protected Mode Interface (DPMI).
 
The ''flVDMStatus''flags indicate:
 
*DPMI was initialized (protected mode was enabled) <br />*16-bit or 32-bit <br />*The current execution mode (V86 or protected)
 
These flags and their values are:
 
<pre class="western">  VDM_STATUS_VPM_32        0x00000001      /* 32-bit DPMI application  */
  VDM_STATUS_VPM_APP        0x00000002      /* DPMI application started  */
  VDM_STATUS_VPM_EXEC      0x00000004      /* In DOS session protected mode*/
  VDM_STATUS_VPM_IF_FLAG    0x00000010      /* Virtual IF flag          */
  VDM_STATUS_VPM_PERM      0x00000080      /* Protected mode allowed?  */
  VDM_STATUS_VPM_XDOS      0x00000100      /* DOS API extension active? */</pre>
 
 
 
 
=== VDHChangeVPMIF - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCheckPagePerm ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  checks  Ring  3  page  permissions  for  a  range  of  pages .
This  service  fails  if  a  Ring  3  client  faults  on  any  of  the  pages  that
have  been  checked .
* /
 
include  mvdm . inc
 
EXTERN    VDHCheckPagePerm : NEAR
BasePage    DD  ?      ;    Base  virtual  page  number
Reserved    DD  ?      ;    Reserved ;  must  be  set  to  zero
NumPages    DD  ?      ;    Number  of  pages  to  verify
Flag        DD  ?      ;    Flag
 
PUSH      BasePage    ;    Push  BasePage
PUSH      Reserved    ;    Push  Reserved
PUSH      NumPages    ;    Push  NumPages
PUSH      Flag        ;    Push  Flag
 
CALL      VDHCheckPagePerm  ;  Call  the  function </pre>
 
 
 
 
=== VDHCheckPagePerm - Format ===
 
 
 
<pre class="western">/*
 
This  function  checks  Ring  3  page  permissions  for  a  range  of  pages .
This  service  fails  if  a  Ring  3  client  faults  on  any  of  the  pages  that
have  been  checked .
* /
 
include  mvdm . inc
 
EXTERN    VDHCheckPagePerm : NEAR
BasePage    DD  ?      ;    Base  virtual  page  number
Reserved    DD  ?      ;    Reserved ;  must  be  set  to  zero
NumPages    DD  ?      ;    Number  of  pages  to  verify
Flag        DD  ?      ;    Flag
 
PUSH      BasePage    ;    Push  BasePage
PUSH      Reserved    ;    Push  Reserved
PUSH      NumPages    ;    Push  NumPages
PUSH      Flag        ;    Push  Flag
 
CALL      VDHCheckPagePerm  ;  Call  the  function </pre>
 
 
 
 
=== VDHCheckPagePerm Parameter - BasePage ===
 
'''BasePage'''(DD) Base virtual page number.
 
 
 
 
 
=== VDHCheckPagePerm Parameter - Reserved ===
 
'''Reserved'''(DD) Reserved. Must be set to ''0''.
 
 
 
 
 
=== VDHCheckPagePerm Parameter - NumPages ===
 
'''NumPages'''(DD) Number of pages to verify.
 
 
 
 
 
=== VDHCheckPagePerm Parameter - Flag ===
 
'''Flag'''(DD) Values are:
 
VPMPG_U Are the pages user-accessible? <br />VPMPG_W Are the pages writable? <br />VPMPG_R Are the pages readable (valid)? <br />VPMPG_X Are the pages executable?
 
 
 
 
 
=== VDHCheckPagePerm Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0.
 
 
 
 
 
=== VDHCheckPagePerm - Parameters ===
 
'''BasePage'''(DD) Base virtual page number.
 
'''Reserved'''(DD) Reserved. Must be set to ''0''.
 
'''NumPages'''(DD) Number of pages to verify.
 
'''Flag'''(DD) Values are:
 
VPMPG_U Are the pages user-accessible? <br />VPMPG_W Are the pages writable? <br />VPMPG_R Are the pages readable (valid)? <br />VPMPG_X Are the pages executable?
 
 
 
 
 
=== VDHCheckPagePerm - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHCheckPagePerm - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCheckVPMIntVector ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  a  nonzero  value  if  the  application
protected - mode  interrupt  vector  is  set .
* /
 
include  mvdm . inc
 
EXTERN    VDHCheckVPMIntVector : NEAR
Vector    DD  ?      ;    Interrupt  vector  number
 
PUSH      Vector    ;    Push  Vector
 
CALL      VDHCheckVPMIntVecto ;  Call  the  function </pre>
 
 
 
 
=== VDHCheckVPMIntVector - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  a  nonzero  value  if  the  application
protected - mode  interrupt  vector  is  set .
* /
 
include  mvdm . inc
 
EXTERN    VDHCheckVPMIntVector : NEAR
Vector    DD  ?      ;    Interrupt  vector  number
 
PUSH      Vector    ;    Push  Vector
 
CALL      VDHCheckVPMIntVecto ;  Call  the  function </pre>
 
 
 
 
=== VDHCheckVPMIntVector Parameter - Vector ===
 
'''Vector'''(DD) Interrupt vector number.
 
 
 
 
 
=== VDHCheckVPMIntVector Return Value - rc ===
 
Success If the function is successful it returns a nonzero value.
 
Failure If there is no user-registered interrupt handler for the interrupt in ''Vector'', the function returns 0 (zero).
 
 
 
 
 
=== VDHCheckVPMIntVector - Parameters ===
 
'''Vector'''(DD) Interrupt vector number.
 
 
 
 
 
=== VDHCheckVPMIntVector - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: There must be a DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHCheckVPMIntVector - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHClearVIRR ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  clears  the  virtual  Interrupt  Request  Register  ( IRR )  in
the  Virtual  Programmable  Interrupt  Controller  ( VPIC )  of  the  specified
DOS  session  for  the  IRQ  specified .
The  simulation  of  interrupts  to  the
specified  DOS  session  is  stopped  on  this  IRQ  level .
* /
 
include  mvdm . inc
 
EXTERN    VDHClearVIRR : NEAR
VDMHandle    DD  ?      ;    DOS  session  handle
IRQHandle    DD  ?      ;    IRQ  handle  from  VDHOpenVIRQ
 
PUSH      VDMHandle    ;    Push  VDMHandle
PUSH      IRQHandle    ;    Push  IRQHandle
 
CALL      VDHClearVIRR    ;  Call  the  function </pre>
 
 
 
 
=== VDHClearVIRR - Format ===
 
 
 
<pre class="western">/*
 
This  function  clears  the  virtual  Interrupt  Request  Register  ( IRR )  in
the  Virtual  Programmable  Interrupt  Controller  ( VPIC )  of  the  specified
DOS  session  for  the  IRQ  specified .
The  simulation  of  interrupts  to  the
specified  DOS  session  is  stopped  on  this  IRQ  level .
* /
 
include  mvdm . inc
 
EXTERN    VDHClearVIRR : NEAR
VDMHandle    DD  ?      ;    DOS  session  handle
IRQHandle    DD  ?      ;    IRQ  handle  from  VDHOpenVIRQ
 
PUSH      VDMHandle    ;    Push  VDMHandle
PUSH      IRQHandle    ;    Push  IRQHandle
 
CALL      VDHClearVIRR    ;  Call  the  function </pre>
 
 
 
 
=== VDHClearVIRR Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
 
 
 
 
=== VDHClearVIRR Parameter - IRQHandle ===
 
'''IRQHandle'''(DD) IRQ handle from ''VDHOpenVIRQ''.
 
 
 
 
 
=== VDHClearVIRR Return Value - rc ===
 
Success If the function was successful, it returns nothing.
 
Failure If either of the parameters is invalid, a system halt occurs.
 
 
 
 
 
=== VDHClearVIRR - Parameters ===
 
'''VDMHandle'''(DD) DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
'''IRQHandle'''(DD) IRQ handle from ''VDHOpenVIRQ''.
 
 
 
 
 
=== VDHClearVIRR - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHClearVIRR - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHClose ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  closes  a  file  or  device  that  was  opened  with
VDHOpen .
* /
 
include  mvdm . inc
 
EXTERN    VDHClose : NEAR
FileHandle    DW  ?      ;    Handle  to  the  file  or  device  to  close
 
PUSH      FileHandle    ;    Push  FileHandle
 
CALL      VDHClose    ;  Call  the  function </pre>
 
 
 
 
=== VDHClose - Format ===
 
 
 
<pre class="western">/*
 
This  function  closes  a  file  or  device  that  was  opened  with
VDHOpen .
* /
 
include  mvdm . inc
 
EXTERN    VDHClose : NEAR
FileHandle    DW  ?      ;    Handle  to  the  file  or  device  to  close
 
PUSH      FileHandle    ;    Push  FileHandle
 
CALL      VDHClose    ;  Call  the  function </pre>
 
 
 
 
=== VDHClose Parameter - FileHandle ===
 
'''FileHandle'''(DW) Handle (from ''VDHOpen'') to the file or device to close.
 
 
 
 
 
=== VDHClose Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''FileHandle''is invalid or if the DOS session is not in the DOS session-task context, a system halt occurs.
 
 
 
 
 
=== VDHClose - Parameters ===
 
'''FileHandle'''(DW) Handle (from ''VDHOpen'') to the file or device to close.
 
 
 
 
 
=== VDHClose - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: Any handles opened by the virtual device driver for the terminating DOS session must be closed.
 
 
 
 
 
=== VDHClose - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCloseVDD ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  closes  a
virtual  device  driver / virtual  device  driver  ( VDD / VDD )
Inter - Device - Driver   Communication  ( IDC )  session  that  was  opened
with  VDHOpenVDD .
* /
 
include  mvdm . inc
 
EXTERN    VDHCloseVDD : NEAR
VDDHandle    DD  ?      ;    Handle  to  the  file  or  device  to  close
 
PUSH      VDDHandle    ;    Push  VDDHandle
 
CALL      VDHCloseVDD    ;  Call  the  function </pre>
 
 
 
 
=== VDHCloseVDD - Format ===
 
 
 
<pre class="western">/*
 
This  function  closes  a
virtual  device  driver / virtual  device  driver  ( VDD / VDD )
Inter - Device - Driver  Communication  ( IDC )  session  that  was  opened
with  VDHOpenVDD .
* /
 
include  mvdm . inc
 
EXTERN    VDHCloseVDD : NEAR
VDDHandle    DD  ?      ;    Handle  to  the  file  or  device  to  close
 
PUSH      VDDHandle    ;    Push  VDDHandle
 
CALL      VDHCloseVDD    ;  Call  the  function </pre>
 
 
 
 
=== VDHCloseVDD Parameter - VDDHandle ===
 
'''VDDHandle'''(DD) Handle (from ''VDHOpenVDD'') to the virtual device driver to close.
 
 
 
 
 
=== VDHCloseVDD Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''VDMHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHCloseVDD - Parameters ===
 
'''VDDHandle'''(DD) Handle (from ''VDHOpenVDD'') to the virtual device driver to close.
 
 
 
 
 
=== VDHCloseVDD - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: If a virtual device driver has a VDD/VDD session for a particular DOS session, that session is closed when the DOS session terminates.
 
Notes: This service is used to close the type of VDD/VDD connections, which are temporary or are on a per-DOS session basis.
 
 
 
 
 
=== VDHCloseVDD - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCloseVIRQ ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  closes  the  virtual  IRQ  handle  passed  to  it .
* /
 
include  mvdm . inc
 
EXTERN    VDHCloseVIRQ : NEAR
IRQHandl    DD  ?      ;    Handle  of  the  virtual  device  driver  to  close
 
PUSH      IRQHandl    ;    Push  IRQHandl
 
CALL      VDHCloseVIRQ  ;  Call  the  function </pre>
 
 
 
 
=== VDHCloseVIRQ - Format ===
 
 
 
<pre class="western">/*
 
This  function  closes  the  virtual  IRQ  handle  passed  to  it .
* /
 
include  mvdm . inc
 
EXTERN    VDHCloseVIRQ : NEAR
IRQHandl    DD  ?      ;    Handle  of  the  virtual  device  driver  to  close
 
PUSH      IRQHandl    ;    Push  IRQHandl
 
CALL      VDHCloseVIRQ  ;  Call  the  function </pre>
 
 
 
 
=== VDHCloseVIRQ Parameter - IRQHandl ===
 
'''IRQHandl'''(DD) Handle to the IRQ (from ''VDHOpenVIRQ'') to close.
 
 
 
 
 
=== VDHCloseVIRQ Return Value - rc ===
 
Success If the function was successful, it returns nothing.
 
Failure If ''IRQHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHCloseVIRQ - Parameters ===
 
'''IRQHandl'''(DD) Handle to the IRQ (from ''VDHOpenVIRQ'') to close.
 
 
 
 
 
=== VDHCloseVIRQ - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHCloseVIRQ - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCopyMem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  copies  memory  from  one  user  linear  address  to  another .
* /
 
include  mvdm . inc
 
EXTERN    VDHCopyMem : NEAR
Source        DD  ?      ;    Address  of  the  data  to  copy
Destination    DD  ?      ;    Address  to  copy  the  data  to
NumBytes      DD  ?      ;    Number  of  bytes  to  copy
 
PUSH      Source        ;    Push  Source
PUSH      Destination    ;    Push  Destination
PUSH      NumBytes      ;    Push  NumBytes
 
CALL      VDHCopyMem      ;  Call  the  function </pre>
 
 
 
 
=== VDHCopyMem - Format ===
 
 
 
<pre class="western">/*
 
This  function  copies  memory  from  one  user  linear  address  to  another .
* /
 
include  mvdm . inc
 
EXTERN    VDHCopyMem : NEAR
Source        DD  ?      ;    Address  of  the  data  to  copy
Destination    DD  ?      ;    Address  to  copy  the  data  to
NumBytes      DD  ?      ;    Number  of  bytes  to  copy
 
PUSH      Source        ;    Push  Source
PUSH      Destination    ;    Push  Destination
PUSH      NumBytes      ;    Push  NumBytes
 
CALL      VDHCopyMem      ;  Call  the  function </pre>
 
 
 
 
=== VDHCopyMem Parameter - Source ===
 
'''Source'''(DD) Address of the source data to be copied.
 
 
 
 
 
=== VDHCopyMem Parameter - Destination ===
 
'''Destination'''(DD) Address to which the data is to be copied.
 
 
 
 
 
=== VDHCopyMem Parameter - NumBytes ===
 
'''NumBytes'''(DD) Number of bytes to copy.
 
 
 
 
 
=== VDHCopyMem Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''NumBytes''is 0 (zero), a system halt occurs.
 
 
 
 
 
=== VDHCopyMem - Parameters ===
 
'''Source'''(DD) Address of the source data to be copied.
 
'''Destination'''(DD) Address to which the data is to be copied.
 
'''NumBytes'''(DD) Number of bytes to copy.
 
 
 
 
 
=== VDHCopyMem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Protection faults are handled as if a user application had performed the access. Therefore, writing to an invalid page causes a virtual device driver page fault handler to gain control. If there is no virtual device driver fault handler, a &quot;don't care&quot; page is mapped in at the faulting linear address.
 
Note that touching invalid pages is allowed only in the context of the DOS session. A virtual device driver cannot touch invalid pages through the HVDM (DOS session Handle) alias region if it is not in the context of that DOS session. A virtual device driver that violates this rule causes a system halt.
 
This function yields the CPU if it is necessary to ensure that the thread dispatch latency limit is not exceeded. This function also supports overlapping linear regions. However, the results are undefined when copying between regions with aliases (through ''VDHMapPages'') to the same physical page.
 
If necessary, ''VDHLockMem''is used to ensure that the status of the source and destination linear ranges does not change. This is required only if the source and destination ranges are in private DOS session memory (accessed through the HVDM), and the call to ''VDHCopyMem''is made in the context of some other process.
 
 
 
 
 
=== VDHCopyMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCreateBlockPool ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  creates  a  pool  of  memory  blocks  of  a  specified  size .
The  blocks  are  allocated  from  the  system  area  so  that  the  block  addresses
are  valid  in  all  process  contexts .
* /
 
include  mvdm . inc
 
EXTERN    VDHCreateBlockPool : NEAR
BlockSize    DD  ?      ;    Size  of  block  to  initialize  ( in  bytes )
OptionFlag    DD  ?      ;    Allocation  options  bit  flag
 
PUSH      BlockSize    ;    Push  BlockSize
PUSH      OptionFlag    ;    Push  OptionFlag
 
CALL      VDHCreateBlockPool    ;  Call  the  function </pre>
 
 
 
 
=== VDHCreateBlockPool - Format ===
 
 
 
<pre class="western">/*
 
This  function  creates  a  pool  of  memory  blocks  of  a  specified  size .
The  blocks  are  allocated  from  the  system  area  so  that  the  block  addresses
are  valid  in  all  process  contexts .
* /
 
include  mvdm . inc
 
EXTERN    VDHCreateBlockPool : NEAR
BlockSize    DD  ?      ;    Size  of  block  to  initialize  ( in  bytes )
OptionFlag    DD  ?      ;    Allocation  options  bit  flag
 
PUSH      BlockSize    ;    Push  BlockSize
PUSH      OptionFlag    ;    Push  OptionFlag
 
CALL      VDHCreateBlockPool    ;  Call  the  function </pre>
 
 
 
 
=== VDHCreateBlockPool Parameter - BlockSize ===
 
'''BlockSize'''(DD) Size of block to initialize (in bytes).
 
 
 
 
 
=== VDHCreateBlockPool Parameter - OptionFlag ===
 
'''OptionFlag'''(DD) Allocation options bit flag. Possible value:
 
VDHCBP_SWAPPABLE Blocks are allocated from the swappable heap. Otherwise, blocks are allocated from the fixed heap and can be accessed at hardware interrupt time.
 
 
 
 
 
=== VDHCreateBlockPool Return Value - rc ===
 
Success If the function is successful, it returns a handle to the pool of memory blocks.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''OptionFlag''is invalid, or if ''BlockSize''is equal to 0 (zero), a system halt occurs.
 
 
 
 
 
=== VDHCreateBlockPool - Parameters ===
 
'''BlockSize'''(DD) Size of block to initialize (in bytes).
 
'''OptionFlag'''(DD) Allocation options bit flag. Possible value:
 
VDHCBP_SWAPPABLE Blocks are allocated from the swappable heap. Otherwise, blocks are allocated from the fixed heap and can be accessed at hardware interrupt time.
 
 
 
 
 
=== VDHCreateBlockPool - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: Any block pools allocated by a virtual device driver for use by the terminating DOS session is freed by using ''VDHDestroyBlockPool''.
 
 
 
 
 
=== VDHCreateBlockPool - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCreateSel ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  creates  a  GDT  selector  that  maps  a  linear  range .
This  service  is  used  to  create  a  16 : 16  pointer ,  which  is  passed
to  a  16 - bit  physical  device  driver .
* /
 
include  mvdm . inc
 
EXTERN    VDHCreateSel : NEAR
LinearAddress    DD  ?      ;    Linear  address  of  the  start  of  the  buffer
BufferSize      DD  ?      ;    Size  of  the  buffer  in  bytes
 
PUSH      LinearAddress    ;    Push  LinearAddress
PUSH      BufferSize      ;    Push  BufferSize
 
CALL      VDHCreateSel        ;  Call  the  function </pre>
 
 
 
 
=== VDHCreateSel - Format ===
 
 
 
<pre class="western">/*
 
This  function  creates  a  GDT  selector  that  maps  a  linear  range .
This  service  is  used  to  create  a  16 : 16  pointer ,  which  is  passed
to  a  16 - bit  physical  device  driver .
* /
 
include  mvdm . inc
 
EXTERN    VDHCreateSel : NEAR
LinearAddress    DD  ?      ;    Linear  address  of  the  start  of  the  buffer
BufferSize      DD  ?      ;    Size  of  the  buffer  in  bytes
 
PUSH      LinearAddress    ;    Push  LinearAddress
PUSH      BufferSize      ;    Push  BufferSize
 
CALL      VDHCreateSel        ;  Call  the  function </pre>
 
 
 
 
=== VDHCreateSel Parameter - LinearAddress ===
 
'''LinearAddress'''(DD) Linear address of the beginning of the buffer.
 
 
 
 
 
=== VDHCreateSel Parameter - BufferSize ===
 
'''BufferSize'''(DD) Size of the buffer in bytes. The expected range is 0-65535 with 0 interpreted as 65536.
 
 
 
 
 
=== VDHCreateSel Return Value - rc ===
 
Success If the function is successful, it returns a nonzero selector value such that SELECTOR:0 points to the first byte of the linear range.
 
Failure If ''BufferSize''is greater than 65535 or if there are no more selectors available, a system halt occurs.
 
 
 
 
 
=== VDHCreateSel - Parameters ===
 
'''LinearAddress'''(DD) Linear address of the beginning of the buffer.
 
'''BufferSize'''(DD) Size of the buffer in bytes. The expected range is 0-65535 with 0 interpreted as 65536.
 
 
 
 
 
=== VDHCreateSel - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: Any selectors created to map memory in the terminating DOS session must be destroyed with ''VDHDestroySel''. The virtual device driver must ensure that any physical device driver that was given these selectors is finished with them.
 
Notes: The linear address must be in system memory. To create a 16:16 pointer to a DOS session address (in the 0 to 1MB+64KB range), use the HVDM (DOS session handle) alias linear address. ''VDHDestroySel''must be called when finished with this pointer.
 
 
 
 
 
=== VDHCreateSel - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHCreateSem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  to  create  an  event  or  mutex  semaphore .
* /
 
include  mvdm . inc
 
EXTERN    VDHCreateSem : NEAR
SemHandlePointer    DD  ?      ;    Semaphore  handle  address
SemType              DD  ?      ;    Type  of  semaphore  of  create
 
PUSH      SemHandlePointer    ;    Push  SemHandlePointer
PUSH      SemType              ;    Push  SemType
 
CALL      VDHCreateSem          ;  Call  the  function </pre>
 
 
 
 
=== VDHCreateSem - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  to  create  an  event  or  mutex  semaphore .
* /
 
include  mvdm . inc
 
EXTERN    VDHCreateSem : NEAR
SemHandlePointer    DD  ?      ;    Semaphore  handle  address
SemType              DD  ?      ;    Type  of  semaphore  of  create
 
PUSH      SemHandlePointer    ;    Push  SemHandlePointer
PUSH      SemType              ;    Push  SemType
 
CALL      VDHCreateSem          ;  Call  the  function </pre>
 
 
 
 
=== VDHCreateSem Parameter - SemHandlePointer ===
 
'''SemHandlePointer'''(DD) Semaphore handle address.
 
 
 
 
 
=== VDHCreateSem Parameter - SemType ===
 
'''SemType'''(DD) Type of semaphore to create.
 
Values are:
 
VDH_EVENTSEM Event semaphore <br />VDH_MUTEXSEM Mutex semaphore
 
 
 
 
 
=== VDHCreateSem Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value and places a handle to the semaphore in ''SemHandlePointer''.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. An invalid semaphore type causes a system halt to occur.
 
 
 
 
 
=== VDHCreateSem - Parameters ===
 
'''SemHandlePointer'''(DD) Semaphore handle address.
 
'''SemType'''(DD) Type of semaphore to create.
 
Values are:
 
VDH_EVENTSEM Event semaphore <br />VDH_MUTEXSEM Mutex semaphore
 
 
 
 
 
=== VDHCreateSem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: These semaphores are global and are not attached to a specific DOS session. If a virtual device driver maintains semaphores on a per-DOS session basis, it destroys the semaphores by using ''VDHDestroySem''when the DOS session they are associated with is terminated.
 
 
 
 
 
=== VDHCreateSem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDecodeProperty ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
This function decodes the specified format of a property string.
(See Notes)
*/
 
include mvdm.inc
 
EXTERN  VDHDecodeProperty:NEAR
ppProperty      DD ?    ;  Pointer to a pointer to property string
StartNumberPtr  DD ?    ;  Location to return the starting number
EndNumberPtr    DD ?    ;  Location to return the ending number
BaseFlag        DD ?    ;  Flag indicating the numeric base to use
 
PUSH    ppProperty      ;  Push ppProperty
PUSH    StartNumberPtr  ;  Push StartNumberPtr
PUSH    EndNumberPtr    ;  Push EndNumberPtr
PUSH    BaseFlag        ;  Push BaseFlag
 
CALL    VDHDecodeProperty      ; Call the function</pre>
 
 
 
 
=== VDHDecodeProperty - Format ===
 
 
 
<pre class="western">/*
This function decodes the specified format of a property string.
(See Notes)
*/
 
include mvdm.inc
 
EXTERN  VDHDecodeProperty:NEAR
ppProperty      DD ?    ;  Pointer to a pointer to property string
StartNumberPtr  DD ?    ;  Location to return the starting number
EndNumberPtr    DD ?    ;  Location to return the ending number
BaseFlag        DD ?    ;  Flag indicating the numeric base to use
 
PUSH    ppProperty      ;  Push ppProperty
PUSH    StartNumberPtr  ;  Push StartNumberPtr
PUSH    EndNumberPtr    ;  Push EndNumberPtr
PUSH    BaseFlag        ;  Push BaseFlag
 
CALL    VDHDecodeProperty      ; Call the function</pre>
 
 
 
 
=== VDHDecodeProperty Parameter - ppProperty ===
 
'''ppProperty'''(DD) A pointer to a pointer to the property string to be decoded .
 
 
 
 
 
=== VDHDecodeProperty Parameter - StartNumberPtr ===
 
'''StartNumberPtr'''(DD) Location for storing the returned starting number.
 
 
 
 
 
=== VDHDecodeProperty Parameter - EndNumberPtr ===
 
'''EndNumberPtr'''(DD) Location for storing the returned ending number.
 
 
 
 
 
=== VDHDecodeProperty Parameter - BaseFlag ===
 
'''BaseFlag'''(DD) Flag indicating which numeric base to use:
 
VDH_DP_DECIMAL Decimal <br />VDH_DP_HEX Hex
 
 
 
 
 
=== VDHDecodeProperty Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value and the ''ppProperty''pointer is modified to point to the next range in the property string. ''StartNumberPtr''and ''EndNumberPtr''will have the range values. ''ppProperty''is returned NULL after processing the last range.
 
Failure If the function fails, it returns 0, indicating an invalid parameter. If ''BaseFlag''contains an invalid value or if ''ppProperty''is NULL, a system halt occurs.
 
 
 
 
 
=== VDHDecodeProperty - Parameters ===
 
'''ppProperty'''(DD) A pointer to a pointer to the property string to be decoded .
 
'''StartNumberPtr'''(DD) Location for storing the returned starting number.
 
'''EndNumberPtr'''(DD) Location for storing the returned ending number.
 
'''BaseFlag'''(DD) Flag indicating which numeric base to use:
 
VDH_DP_DECIMAL Decimal <br />VDH_DP_HEX Hex
 
 
 
 
 
=== VDHDecodeProperty - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: If a single value is found, ''EndNumberPtr''is a -1. All the numbers are decoded in the specified base. A negative sign is used only as range delimiter. Numbers cannot have more than eight digits or a failure is returned. If this service returns Failure, it is still possible that the contents of ''StartNumberPtr''or ''EndNumberPtr''might have changed.
 
Because pointers passed are from a virtual device driver (not a user), there is no verification of addresses. Bad pointers result in page faults.
 
This function decodes the specified format of a property string as shown below:
 
<pre class="western">String Syntax = &quot;N1-N2,N3-N4,N5,N6-N7,...&quot;</pre>
Notice that N''x''are valid numbers in a specified base.
 
 
 
 
 
=== VDHDecodeProperty - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDestroyBlockPool ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  releases  a  memory  block  pool .
* /
 
include  mvdm . inc
 
EXTERN    VDHDestroyBlockPool : NEAR
PoolHandle    DD  ?      ;    Handle  to  the  memory  block  pool  to  release
 
PUSH      PoolHandle    ;    Push  PoolHandle
 
CALL      VDHDestroyBlockPool    ;  Call  the  function </pre>
 
 
 
 
=== VDHDestroyBlockPool - Format ===
 
 
 
<pre class="western">/*
 
This  function  releases  a  memory  block  pool .
* /
 
include  mvdm . inc
 
EXTERN    VDHDestroyBlockPool : NEAR
PoolHandle    DD  ?      ;    Handle  to  the  memory  block  pool  to  release
 
PUSH      PoolHandle    ;    Push  PoolHandle
 
CALL      VDHDestroyBlockPool    ;  Call  the  function </pre>
 
 
 
 
=== VDHDestroyBlockPool Parameter - PoolHandle ===
 
'''PoolHandle'''(DD) Handle to the memory block pool to release.
 
 
 
 
 
=== VDHDestroyBlockPool Return Value - rc ===
 
Success If the function was successful, it returns nothing.
 
Failure An invalid memory block pool handle causes a system halt to occur.
 
 
 
 
 
=== VDHDestroyBlockPool - Parameters ===
 
'''PoolHandle'''(DD) Handle to the memory block pool to release.
 
 
 
 
 
=== VDHDestroyBlockPool - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHDestroyBlockPool - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDestroySel ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  destroys
a  GDT  selector  created  by  VDHCreateSel .
* /
 
include  mvdm . inc
 
EXTERN    VDHDestroySel : NEAR
GDTSelector    DW  ?      ;    GDT  selector  to  destroy
 
PUSH      GDTSelector    ;    Push  GDTSelector
 
CALL      VDHDestroySel      ;  Call  the  function </pre>
 
 
 
 
=== VDHDestroySel - Format ===
 
 
 
<pre class="western">/*
 
This  function  destroys
a  GDT  selector  created  by  VDHCreateSel .
* /
 
include  mvdm . inc
 
EXTERN    VDHDestroySel : NEAR
GDTSelector    DW  ?      ;    GDT  selector  to  destroy
 
PUSH      GDTSelector    ;    Push  GDTSelector
 
CALL      VDHDestroySel      ;  Call  the  function </pre>
 
 
 
 
=== VDHDestroySel Parameter - GDTSelector ===
 
'''GDTSelector'''(DW) GDT selector to be destroyed.
 
 
 
 
 
=== VDHDestroySel Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''GDTSelector''was not created by ''VDHCreateSel'', a system halt occurs.
 
 
 
 
 
=== VDHDestroySel - Parameters ===
 
'''GDTSelector'''(DW) GDT selector to be destroyed.
 
 
 
 
 
=== VDHDestroySel - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: All selectors created with ''VDHCreateSel''that map the terminating DOS session must be destroyed.
 
 
 
 
 
=== VDHDestroySel - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDestroySem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  destroys  a  semaphore  previously  created  with
VDHCreateSem .
The  semaphore  must  be  posted  or  unowned  before  calling  this  service .
* /
 
include  mvdm . inc
 
EXTERN    VDHDestroySem : NEAR
SemHandle    DD  ?      ;    Semaphore  handle  to  destroy
 
PUSH      SemHandle    ;    Push  SemHandle
 
CALL      VDHDestroySem    ;  Call  the  function </pre>
 
 
 
 
=== VDHDestroySem - Format ===
 
 
 
<pre class="western">/*
 
This  function  destroys  a  semaphore  previously  created  with
VDHCreateSem .
The  semaphore  must  be  posted  or  unowned  before  calling  this  service .
* /
 
include  mvdm . inc
 
EXTERN    VDHDestroySem : NEAR
SemHandle    DD  ?      ;    Semaphore  handle  to  destroy
 
PUSH      SemHandle    ;    Push  SemHandle
 
CALL      VDHDestroySem    ;  Call  the  function </pre>
 
 
 
 
=== VDHDestroySem Parameter - SemHandle ===
 
'''SemHandle'''(DD) Handle of the semaphore to destroy.
 
 
 
 
 
=== VDHDestroySem Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''SemHandle''is invalid or if the semaphore is reset or owned, a system halt occurs.
 
 
 
 
 
=== VDHDestroySem - Parameters ===
 
'''SemHandle'''(DD) Handle of the semaphore to destroy.
 
 
 
 
 
=== VDHDestroySem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHDestroySem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDevBeep ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  performs  the  preempt  beep  request  on  behalf  of  the
requesting  virtual  device  driver .
* /
 
include  mvdm . inc
 
EXTERN    VDHDevBeep : NEAR
Frequency    DD  ?      ;    Frequency  of  the  beep  in  hertz
Duration    DD  ?      ;    Duration  of  the  beep  in  milliseconds
 
PUSH      Frequency    ;    Push  Frequency
PUSH      Duration    ;    Push  Duration
 
CALL      VDHDevBeep    ;  Call  the  function </pre>
 
 
 
 
=== VDHDevBeep - Format ===
 
 
 
<pre class="western">/*
 
This  function  performs  the  preempt  beep  request  on  behalf  of  the
requesting  virtual  device  driver .
* /
 
include  mvdm . inc
 
EXTERN    VDHDevBeep : NEAR
Frequency    DD  ?      ;    Frequency  of  the  beep  in  hertz
Duration    DD  ?      ;    Duration  of  the  beep  in  milliseconds
 
PUSH      Frequency    ;    Push  Frequency
PUSH      Duration    ;    Push  Duration
 
CALL      VDHDevBeep    ;  Call  the  function </pre>
 
 
 
 
=== VDHDevBeep Parameter - Frequency ===
 
'''Frequency'''(DD) Frequency of the beep in hertz.
 
 
 
 
 
=== VDHDevBeep Parameter - Duration ===
 
'''Duration'''(DD) Duration of the beep in milliseconds.
 
 
 
 
 
=== VDHDevBeep Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0.
 
 
 
 
 
=== VDHDevBeep - Parameters ===
 
'''Frequency'''(DD) Frequency of the beep in hertz.
 
'''Duration'''(DD) Duration of the beep in milliseconds.
 
 
 
 
 
=== VDHDevBeep - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHDevBeep - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDevIOCtl ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  allows  a  virtual  device  driver  to  send  device - specific  commands  to  a
physical  device  driver  through  the  generic  IOCtl  interface .
The  parameters  and  error
return  codes  are  identical
to  the  ones  found  in  the  DosDevIOCtl  API .
Refer  to  the
OS / 2  Control  Program  Programming  Reference  
for  a  complete
description  of  each  DosDevIOCtl  API  parameter .
* /
 
include  mvdm . inc
 
EXTERN    VDHDevIOCtl : NEAR
DevHandle          DW  ?      ;    Device  handle  returned  by  VDHOpen  or  VDHPhysicalDisk
Category          DD  ?      ;    Category  of  function  performed
Function          DD  ?      ;    Function  within  category  performed
ParmList          DD  ?      ;    Pointer  to  command - specific  input  parameter  area
ParmLengthMax      DD  ?      ;    Maximum  size  of  input  parameter  area ,  in  bytes
ParmLengthInOut    DD  ?      ;    Pointer  to  length  of  the  parameters  passed ,  in  bytes
DataArea          DD  ?      ;    Pointer  to  the  data  area
DataLengthMax      DD  ?      ;    Maximum  size  of  the  parameters  passed ,  in  bytes
DataLengthInOut    DD  ?      ;    Pointer  to  length  of  the  parameters  passed ,  in  bytes
 
PUSH      DevHandle          ;    Push  DevHandle
PUSH      Category          ;    Push  Category
PUSH      Function          ;    Push  Function
PUSH      ParmList          ;    Push  ParmList
PUSH      ParmLengthMax      ;    Push  ParmLengthMax
PUSH      ParmLengthInOut    ;    Push  ParmLengthInOut
PUSH      DataArea          ;    Push  DataArea
PUSH      DataLengthMax      ;    Push  DataLengthMax
PUSH      DataLengthInOut    ;    Push  DataLengthInOut
 
CALL      VDHDevIOCtl          ;  Call  the  function </pre>
 
 
 
 
=== VDHDevIOCtl - Format ===
 
 
 
<pre class="western">/*
 
This  function  allows  a  virtual  device  driver  to  send  device - specific  commands  to  a
physical  device  driver  through  the  generic  IOCtl  interface .
The  parameters  and  error
return  codes  are  identical
to  the  ones  found  in  the  DosDevIOCtl  API .
Refer  to  the
OS / 2  Control  Program  Programming  Reference
for  a  complete
description  of  each  DosDevIOCtl  API  parameter .
* /
 
include  mvdm . inc
 
EXTERN    VDHDevIOCtl : NEAR
DevHandle          DW  ?      ;    Device  handle  returned  by  VDHOpen  or  VDHPhysicalDisk
Category          DD  ?      ;    Category  of  function  performed
Function          DD  ?      ;    Function  within  category  performed
ParmList          DD  ?      ;    Pointer  to  command - specific  input  parameter  area
ParmLengthMax      DD  ?      ;    Maximum  size  of  input  parameter  area ,  in  bytes
ParmLengthInOut    DD  ?      ;    Pointer  to  length  of  the  parameters  passed ,  in  bytes
DataArea          DD  ?      ;    Pointer  to  the  data  area
DataLengthMax      DD  ?      ;    Maximum  size  of  the  parameters  passed ,  in  bytes
DataLengthInOut    DD  ?      ;    Pointer  to  length  of  the  parameters  passed ,  in  bytes
 
PUSH      DevHandle          ;    Push  DevHandle
PUSH      Category          ;    Push  Category
PUSH      Function          ;    Push  Function
PUSH      ParmList          ;    Push  ParmList
PUSH      ParmLengthMax      ;    Push  ParmLengthMax
PUSH      ParmLengthInOut    ;    Push  ParmLengthInOut
PUSH      DataArea          ;    Push  DataArea
PUSH      DataLengthMax      ;    Push  DataLengthMax
PUSH      DataLengthInOut    ;    Push  DataLengthInOut
 
CALL      VDHDevIOCtl          ;  Call  the  function </pre>
 
 
 
 
=== VDHDevIOCtl Parameter - DevHandle ===
 
'''DevHandle'''(DW) Device handle returned by ''VDHOpen''or ''VDHPhysicalDisk''.
 
 
 
 
 
=== VDHDevIOCtl Parameter - Category ===
 
'''Category'''(DD) Category of function performed.
 
 
 
 
 
=== VDHDevIOCtl Parameter - Function ===
 
'''Function'''(DD) Function within category performed.
 
 
 
 
 
=== VDHDevIOCtl Parameter - ParmList ===
 
'''ParmList'''(DD) Pointer to the command-specific input parameter area.
 
 
 
 
 
=== VDHDevIOCtl Parameter - ParmLengthMax ===
 
'''ParmLengthMax'''(DD) Maximum size of the application input parameter area, in bytes. ''ParmLengthInOut''can be longer than this on input, but not on output.
 
 
 
 
 
=== VDHDevIOCtl Parameter - ParmLengthInOut ===
 
'''ParmLengthInOut'''(DD) Pointer to the length (in bytes) of the parameters passed by the caller in ''ParmList''.
 
 
 
 
 
=== VDHDevIOCtl Parameter - DataArea ===
 
'''DataArea'''(DD) Pointer to the data area.
 
 
 
 
 
=== VDHDevIOCtl Parameter - DataLengthMax ===
 
'''DataLengthMax'''(DD) Maximum size of the application data area, in bytes.
 
 
 
 
 
=== VDHDevIOCtl Parameter - DataLengthInOut ===
 
'''DataLengthInOut'''(DD) Pointer to the length (in bytes) of the parameters passed by the caller in ''ParmList''. ''ParmLengthInOut''can be longer than this on input, but not on output.
 
 
 
 
 
=== VDHDevIOCtl Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. ''VDHGetError''can return the following errors:
 
ERROR_INVALID_HANDLE <br />ERROR_INVALID_FUNCTION <br />ERROR_INVALID_CATEGORY <br />ERROR_INVALID_DRIVE <br />ERROR_INVALID_PARAMETER.
 
If the function is called when not at DOS session-task time, a system halt occurs.
 
 
 
 
 
=== VDHDevIOCtl - Parameters ===
 
'''DevHandle'''(DW) Device handle returned by ''VDHOpen''or ''VDHPhysicalDisk''.
 
'''Category'''(DD) Category of function performed.
 
'''Function'''(DD) Function within category performed.
 
'''ParmList'''(DD) Pointer to the command-specific input parameter area.
 
'''ParmLengthMax'''(DD) Maximum size of the application input parameter area, in bytes. ''ParmLengthInOut''can be longer than this on input, but not on output.
 
'''ParmLengthInOut'''(DD) Pointer to the length (in bytes) of the parameters passed by the caller in ''ParmList''.
 
'''DataArea'''(DD) Pointer to the data area.
 
'''DataLengthMax'''(DD) Maximum size of the application data area, in bytes.
 
'''DataLengthInOut'''(DD) Pointer to the length (in bytes) of the parameters passed by the caller in ''ParmList''. ''ParmLengthInOut''can be longer than this on input, but not on output.
 
 
 
 
 
=== VDHDevIOCtl - Purpose ===
 
Context Issues: This function can be called only in the DOS session task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Addresses (pointers) inside device-specific Data or Parameter Packets are not translated.
 
 
 
 
 
=== VDHDevIOCtl - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHDisarmTimerHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  cancels
a  timer  that  was  installed  by  VDHArmTimerHook
before  the  handler  was  called .
* /
 
include  mvdm . inc
 
EXTERN    VDHDisarmTimerHook : NEAR
TimerHook    DD  ?      ;    Handle  to  the  timer  hook  to  disarm
 
PUSH      TimerHook    ;    Push  TimerHook
 
CALL      VDHDisarmTimerHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHDisarmTimerHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  cancels
a  timer  that  was  installed  by  VDHArmTimerHook
before  the  handler  was  called .
* /
 
include  mvdm . inc
 
EXTERN    VDHDisarmTimerHook : NEAR
TimerHook    DD  ?      ;    Handle  to  the  timer  hook  to  disarm
 
PUSH      TimerHook    ;    Push  TimerHook
 
CALL      VDHDisarmTimerHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHDisarmTimerHook Parameter - TimerHook ===
 
'''TimerHook'''(DD) Handle to the timer hook to disarm.
 
 
 
 
 
=== VDHDisarmTimerHook Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''TimerHook''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHDisarmTimerHook - Parameters ===
 
'''TimerHook'''(DD) Handle to the timer hook to disarm.
 
 
 
 
 
=== VDHDisarmTimerHook - Purpose ===
 
Context Issues: This function can be called in the initialization, task, or interrupt context.
 
DOS Session Terminations: Any timer hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager at DOS session termination.
 
 
 
 
 
=== VDHDisarmTimerHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHEndUseVPMStack ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  must  be  called  once  with  every  call  made  to
VDHBeginUseVPMStack .
It  switches  back  to  the  original  DOS  session  protected - mode  stack  when
the  use  count  goes  to  zero .
* /
 
include  mvdm . inc
 
EXTERN    VDHEndUseVPMStack : NEAR
                DD  ?
 
PUSH                      ;    Push
 
CALL      VDHEndUseVPMStack      ;  Call  the  function </pre>
 
 
 
 
=== VDHEndUseVPMStack - Format ===
 
 
 
<pre class="western">/*
 
This  function  must  be  called  once  with  every  call  made  to
VDHBeginUseVPMStack .
It  switches  back  to  the  original  DOS  session  protected - mode  stack  when
the  use  count  goes  to  zero .
* /
 
include  mvdm . inc
 
EXTERN    VDHEndUseVPMStack : NEAR
                DD  ?
 
PUSH                      ;    Push
 
CALL      VDHEndUseVPMStack      ;  Call  the  function </pre>
 
 
 
 
=== VDHEndUseVPMStack Parameter - ===
 
(DD) None.
 
 
 
 
 
=== VDHEndUseVPMStack Return Value - ===
 
None.
 
 
 
 
 
=== VDHEndUseVPMStack - Parameters ===
 
(DD) None.
 
 
 
 
 
=== VDHEndUseVPMStack - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: There must be a DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHEndUseVPMStack - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHEnumerateVDMs ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  to  run  a  worker  function  for
each  DOS  session  in  the  system .
The  worker  function  can  stop  the  enumeration  by  returning  0 .
* /
 
include  mvdm . inc
 
EXTERN    VDHEnumerateVDMs : NEAR
WorkerFcn    DD  ?      ;    Worker  function
FcnData      DD  ?      ;    Function - specific  data  to  be  passed  each  call
 
PUSH      WorkerFcn    ;    Push  WorkerFcn
PUSH      FcnData      ;    Push  FcnData
 
CALL      VDHEnumerateVDMs    ;  Call  the  function </pre>
 
 
 
 
=== VDHEnumerateVDMs - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  to  run  a  worker  function  for
each  DOS  session  in  the  system .
The  worker  function  can  stop  the  enumeration  by  returning  0 .
* /
 
include  mvdm . inc
 
EXTERN    VDHEnumerateVDMs : NEAR
WorkerFcn    DD  ?      ;    Worker  function
FcnData      DD  ?      ;    Function - specific  data  to  be  passed  each  call
 
PUSH      WorkerFcn    ;    Push  WorkerFcn
PUSH      FcnData      ;    Push  FcnData
 
CALL      VDHEnumerateVDMs    ;  Call  the  function </pre>
 
 
 
 
=== VDHEnumerateVDMs Parameter - WorkerFcn ===
 
'''WorkerFcn'''(DD) Worker function, the routine that does the work.
 
The worker function uses the following interface:
 
<pre class="western">EnumHook  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hVDM  - Handle to DOS session
;          [ESP + 4] - ulData - Function-specific data
;    EXIT  SUCCESS - Return a non-zero value in EAX, enumeration continues
;          FAILURE - Return 0 in EAX, stop enumeration</pre>
 
 
 
 
 
 
=== VDHEnumerateVDMs Parameter - FcnData ===
 
'''FcnData'''(DD) Function-specific data to be passed each call.
 
 
 
 
 
=== VDHEnumerateVDMs Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 indicating that a worker function stopped the enumeration.
 
 
 
 
 
=== VDHEnumerateVDMs - Parameters ===
 
'''WorkerFcn'''(DD) Worker function, the routine that does the work.
 
The worker function uses the following interface:
 
<pre class="western">EnumHook  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hVDM  - Handle to DOS session
;          [ESP + 4] - ulData - Function-specific data
;    EXIT  SUCCESS - Return a non-zero value in EAX, enumeration continues
;          FAILURE - Return 0 in EAX, stop enumeration</pre>
 
 
'''FcnData'''(DD) Function-specific data to be passed each call.
 
 
 
 
 
=== VDHEnumerateVDMs - Purpose ===
 
Context Issues: This function can be called in the task and interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHEnumerateVDMs - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHExchangeMem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  exchanges  the  contents  of  two  regions
of  linear  address  space .
Overlapping  regions  are  not  supported .
* /
 
include  mvdm . inc
 
EXTERN    VDHExchangeMem : NEAR
Source        DD  ?      ;    Source  data  address
Destination    DD  ?      ;    Destination  address
NumBytes      DD  ?      ;    Number  of  bytes  to  be  exchanged
 
PUSH      Source        ;    Push  Source
PUSH      Destination    ;    Push  Destination
PUSH      NumBytes      ;    Push  NumBytes
 
CALL      VDHExchangeMem      ;  Call  the  function </pre>
 
 
 
 
=== VDHExchangeMem - Format ===
 
 
 
<pre class="western">/*
 
This  function  exchanges  the  contents  of  two  regions
of  linear  address  space .
Overlapping  regions  are  not  supported .
* /
 
include  mvdm . inc
 
EXTERN    VDHExchangeMem : NEAR
Source        DD  ?      ;    Source  data  address
Destination    DD  ?      ;    Destination  address
NumBytes      DD  ?      ;    Number  of  bytes  to  be  exchanged
 
PUSH      Source        ;    Push  Source
PUSH      Destination    ;    Push  Destination
PUSH      NumBytes      ;    Push  NumBytes
 
CALL      VDHExchangeMem      ;  Call  the  function </pre>
 
 
 
 
=== VDHExchangeMem Parameter - Source ===
 
'''Source'''(DD) Address of the source data.
 
 
 
 
 
=== VDHExchangeMem Parameter - Destination ===
 
'''Destination'''(DD) Address of the target region.
 
 
 
 
 
=== VDHExchangeMem Parameter - NumBytes ===
 
'''NumBytes'''(DD) Number of bytes to exchange.
 
 
 
 
 
=== VDHExchangeMem Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHExchangeMem - Parameters ===
 
'''Source'''(DD) Address of the source data.
 
'''Destination'''(DD) Address of the target region.
 
'''NumBytes'''(DD) Number of bytes to exchange.
 
 
 
 
 
=== VDHExchangeMem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This function fails if the two memory regions to be exchanged overlap. Protection faults are handled as if a user application had performed the access. Therefore, writing to read-only pages or invalid page -table entries causes a virtual device driver page fault handler to gain control or causes the default behavior (that is, DOS session termination). This function also yields the CPU, if it is necessary to ensure that the thread dispatch latency limit is not exceeded.
 
 
 
 
 
=== VDHExchangeMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFindFreePages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  starts  at  a  specified  linear  address  and  searches  linear
memory  ( up  to  a  specified  limit )  for  the  largest  free  linear  memory  block .
The  address  and  size  of  the  largest  region  found  are  returned .
* /
 
include  mvdm . inc
 
EXTERN    VDHFindFreePages : NEAR
StartAddress    DD  ?      ;    Starting  address
Pages          DD  ?      ;    Size  of  the  range  ( in  pages )
 
PUSH      StartAddress    ;    Push  StartAddress
PUSH      Pages          ;    Push  Pages
 
CALL      VDHFindFreePages      ;  Call  the  function </pre>
 
 
 
 
=== VDHFindFreePages - Format ===
 
 
 
<pre class="western">/*
 
This  function  starts  at  a  specified  linear  address  and  searches  linear
memory  ( up  to  a  specified  limit )  for  the  largest  free  linear  memory  block .
The  address  and  size  of  the  largest  region  found  are  returned .
* /
 
include  mvdm . inc
 
EXTERN    VDHFindFreePages : NEAR
StartAddress    DD  ?      ;    Starting  address
Pages          DD  ?      ;    Size  of  the  range  ( in  pages )
 
PUSH      StartAddress    ;    Push  StartAddress
PUSH      Pages          ;    Push  Pages
 
CALL      VDHFindFreePages      ;  Call  the  function </pre>
 
 
 
 
=== VDHFindFreePages Parameter - StartAddress ===
 
'''StartAddress'''(DD) Starting address of the linear memory range to be searched. Must be page-aligned and between 0 and 110000H (1MB+64KB).
 
 
 
 
 
=== VDHFindFreePages Parameter - Pages ===
 
'''Pages'''(DD) On input: The size of the linear memory range to search, in pages.
 
On output: The size of the region found, in pages.
 
 
 
 
 
=== VDHFindFreePages Return Value - rc ===
 
Success If the function is successful, it returns the address of the region found and sets ''Pages''to the size of the region found (in pages).
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHFindFreePages - Parameters ===
 
'''StartAddress'''(DD) Starting address of the linear memory range to be searched. Must be page-aligned and between 0 and 110000H (1MB+64KB).
 
'''Pages'''(DD) On input: The size of the linear memory range to search, in pages.
 
On output: The size of the region found, in pages.
 
 
 
 
 
=== VDHFindFreePages - Purpose ===
 
Context Issues: This function can be called in the initialization context where it searches only the global linear map. This function can also be called in DOS session-task context (DOS session creation only), where it searches only the DOS session's private linear map.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHFindFreePages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFreeBlock ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  releases  a  memory  block  previously
allocated  by  VDHAllocBlock .
The  memory  block  is  returned  to  the  user ' s  memory
block  pool  for  reuse .
* /
 
include  mvdm . inc
 
EXTERN    VDHFreeBlock : NEAR
PoolHandle    DD  ?      ;    Handle  to  a  memory  block  pool
BlockToFree    DD  ?      ;    Address  of  the  memory  block  to  free
 
PUSH      PoolHandle    ;    Push  PoolHandle
PUSH      BlockToFree    ;    Push  BlockToFree
 
CALL      VDHFreeBlock      ;  Call  the  function </pre>
 
 
 
 
=== VDHFreeBlock - Format ===
 
 
 
<pre class="western">/*
 
This  function  releases  a  memory  block  previously
allocated  by  VDHAllocBlock .
The  memory  block  is  returned  to  the  user ' s  memory
block  pool  for  reuse .
* /
 
include  mvdm . inc
 
EXTERN    VDHFreeBlock : NEAR
PoolHandle    DD  ?      ;    Handle  to  a  memory  block  pool
BlockToFree    DD  ?      ;    Address  of  the  memory  block  to  free
 
PUSH      PoolHandle    ;    Push  PoolHandle
PUSH      BlockToFree    ;    Push  BlockToFree
 
CALL      VDHFreeBlock      ;  Call  the  function </pre>
 
 
 
 
=== VDHFreeBlock Parameter - PoolHandle ===
 
'''PoolHandle'''(DD) Handle (from ''VDHCreateBlockPool'') to the pool of memory blocks that contains the memory block to free.
 
 
 
 
 
=== VDHFreeBlock Parameter - BlockToFree ===
 
'''BlockToFree'''(DD) Address of the memory block to free.
 
 
 
 
 
=== VDHFreeBlock Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''BlockPool''is not a valid handle to a memory block pool, or if ''BlockToFree''is not a block allocated from the ''BlockPool''memory block pool, a system halt occurs.
 
 
 
 
 
=== VDHFreeBlock - Parameters ===
 
'''PoolHandle'''(DD) Handle (from ''VDHCreateBlockPool'') to the pool of memory blocks that contains the memory block to free.
 
'''BlockToFree'''(DD) Address of the memory block to free.
 
 
 
 
 
=== VDHFreeBlock - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: The only way to reclaim memory for freed blocks is to call ''VDHDestroyBlockPool''.
 
 
 
 
 
=== VDHFreeBlock - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFreeDMABuffer ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  frees  a  DMA  buffer  previously  allocated
by  VDHAllocDMABuffer .
* /
 
include  mvdm . inc
 
EXTERN    VDHFreeDMABuffer : NEAR
LinearAddress    DD  ?      ;    Starting  linear  address  of  the  DMA  buffer
 
PUSH      LinearAddress    ;    Push  LinearAddress
 
CALL      VDHFreeDMABuffer        ;  Call  the  function </pre>
 
 
 
 
=== VDHFreeDMABuffer - Format ===
 
 
 
<pre class="western">/*
 
This  function  frees  a  DMA  buffer  previously  allocated
by  VDHAllocDMABuffer .
* /
 
include  mvdm . inc
 
EXTERN    VDHFreeDMABuffer : NEAR
LinearAddress    DD  ?      ;    Starting  linear  address  of  the  DMA  buffer
 
PUSH      LinearAddress    ;    Push  LinearAddress
 
CALL      VDHFreeDMABuffer        ;  Call  the  function </pre>
 
 
 
 
=== VDHFreeDMABuffer Parameter - LinearAddress ===
 
'''LinearAddress'''(DD) Starting linear address of the DMA buffer.
 
 
 
 
 
=== VDHFreeDMABuffer Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''LinearAddress''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHFreeDMABuffer - Parameters ===
 
'''LinearAddress'''(DD) Starting linear address of the DMA buffer.
 
 
 
 
 
=== VDHFreeDMABuffer - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHFreeDMABuffer - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFreeHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  disarms  and  frees  a  hook .
* /
 
include  mvdm . inc
 
EXTERN    VDHFreeHook : NEAR
HookHandle    DD  ?      ;    Hook  handle  from  VDHAllocHook
 
PUSH      HookHandle    ;    Push  HookHandle
 
CALL      VDHFreeHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHFreeHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  disarms  and  frees  a  hook .
* /
 
include  mvdm . inc
 
EXTERN    VDHFreeHook : NEAR
HookHandle    DD  ?      ;    Hook  handle  from  VDHAllocHook
 
PUSH      HookHandle    ;    Push  HookHandle
 
CALL      VDHFreeHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHFreeHook Parameter - HookHandle ===
 
'''HookHandle'''(DD) Hook handle (from ''VDHAllocHook'') for the hook to free.
 
 
 
 
 
=== VDHFreeHook Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''HookHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHFreeHook - Parameters ===
 
'''HookHandle'''(DD) Hook handle (from ''VDHAllocHook'') for the hook to free.
 
 
 
 
 
=== VDHFreeHook - Purpose ===
 
Context Issues: This function can be called in the initialization or DOS session-task context.
 
DOS Session Terminations: Any context hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager.
 
 
 
 
 
=== VDHFreeHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFreeMem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  frees  memory  that  was  previously  allocated  by
VDHAllocMem .
* /
 
include  mvdm . inc
 
EXTERN    VDHFreeMem : NEAR
MemAddress    DD  ?      ;    Address  of  the  memory  block  to  free
 
PUSH      MemAddress    ;    Push  MemAddress
 
CALL      VDHFreeMem    ;  Call  the  function </pre>
 
 
 
 
=== VDHFreeMem - Format ===
 
 
 
<pre class="western">/*
 
This  function  frees  memory  that  was  previously  allocated  by
VDHAllocMem .
* /
 
include  mvdm . inc
 
EXTERN    VDHFreeMem : NEAR
MemAddress    DD  ?      ;    Address  of  the  memory  block  to  free
 
PUSH      MemAddress    ;    Push  MemAddress
 
CALL      VDHFreeMem    ;  Call  the  function </pre>
 
 
 
 
=== VDHFreeMem Parameter - MemAddress ===
 
'''MemAddress'''(DD) Address of the memory block to be freed. Pointer is originally obtained from ''VDHAllocMem''.
 
 
 
 
 
=== VDHFreeMem Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''MemAddress''is not an address pointer allocated by ''VDHAllocMem'', a system halt occurs.
 
 
 
 
 
=== VDHFreeMem - Parameters ===
 
'''MemAddress'''(DD) Address of the memory block to be freed. Pointer is originally obtained from ''VDHAllocMem''.
 
 
 
 
 
=== VDHFreeMem - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHFreeMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFreePages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  frees  a  memory  object .
All  the  memory  associated  with  the  memory  object  is  released .
* /
 
include  mvdm . inc
 
EXTERN    VDHFreePages : NEAR
ObjectAddress    DD  ?      ;    Address  of  the  memory  object  to  free
 
PUSH      ObjectAddress    ;    Push  ObjectAddress
 
CALL      VDHFreePages        ;  Call  the  function </pre>
 
 
 
 
=== VDHFreePages - Format ===
 
 
 
<pre class="western">/*
 
This  function  frees  a  memory  object .
All  the  memory  associated  with  the  memory  object  is  released .
* /
 
include  mvdm . inc
 
EXTERN    VDHFreePages : NEAR
ObjectAddress    DD  ?      ;    Address  of  the  memory  object  to  free
 
PUSH      ObjectAddress    ;    Push  ObjectAddress
 
CALL      VDHFreePages        ;  Call  the  function </pre>
 
 
 
 
=== VDHFreePages Parameter - ObjectAddress ===
 
'''ObjectAddress'''(DD) Address of the memory object to free.
 
 
 
 
 
=== VDHFreePages Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''ObjectAddress''was not allocated by ''VDHAllocPages''or ''VDHReallocPages'', a system halt occurs.
 
 
 
 
 
=== VDHFreePages - Parameters ===
 
'''ObjectAddress'''(DD) Address of the memory object to free.
 
 
 
 
 
=== VDHFreePages - Purpose ===
 
Context Issues: This function can be called in the initialization or task context. At initialization time, only global memory can be freed.
 
DOS Session Terminations: Any allocations made in the terminating DOS session's private area, or on behalf of the terminating DOS session, must be released by using ''VDHFreePages''.
 
Notes: This function succeeds only if the linear range specified was allocated by a previous call to ''VDHAllocPages''or ''VDHReallocPages''. Freeing a memory region that was not allocated causes an internal error (a probable system halt).
 
If the region, starting at ''ObjectAddress'', has been broken into two or more regions by calls to ''VDHMapPages'', then ''VDHFreePages''is not used.
 
 
 
 
 
=== VDHFreePages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHFreezeVDM ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  freezes  a  DOS  session ,  which  prevents  it  from  executing .
The  specified  DOS  session  is  not  allowed  to  execute  any  V86 - mode  code  until
VDHThawVDM  is  called .
This  freeze  occurs  when  the  specified  DOS  session  leaves  kernel  mode .
The  DOS  session  does  not  execute  any  V86 - mode  code  from  the  time
VDHFreezeVDM  is  called  until  the
matching  VDHThawVDM  is  called .
* /
 
include  mvdm . inc
 
EXTERN    VDHFreezeVDM : NEAR
VDMHandle    DD  ?      ;    Handle  to  the  DOS  session  to  freeze
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHFreezeVDM    ;  Call  the  function </pre>
 
 
 
 
=== VDHFreezeVDM - Format ===
 
 
 
<pre class="western">/*
 
This  function  freezes  a  DOS  session ,  which  prevents  it  from  executing .
The  specified  DOS  session  is  not  allowed  to  execute  any  V86 - mode  code  until
VDHThawVDM  is  called .
This  freeze  occurs  when  the  specified  DOS  session  leaves  kernel  mode .
The  DOS  session  does  not  execute  any  V86 - mode  code  from  the  time
VDHFreezeVDM  is  called  until  the
matching  VDHThawVDM  is  called .
* /
 
include  mvdm . inc
 
EXTERN    VDHFreezeVDM : NEAR
VDMHandle    DD  ?      ;    Handle  to  the  DOS  session  to  freeze
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHFreezeVDM    ;  Call  the  function </pre>
 
 
 
 
=== VDHFreezeVDM Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) Handle to the DOS session to freeze.
 
 
 
 
 
=== VDHFreezeVDM Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''VDMHandle''is not a valid DOS session handle, a system halt occurs.
 
 
 
 
 
=== VDHFreezeVDM - Parameters ===
 
'''VDMHandle'''(DD) Handle to the DOS session to freeze.
 
 
 
 
 
=== VDHFreezeVDM - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: The DOS Session Manager thaws a frozen DOS session prior to calling any VDM_TERMINATE user hooks.
 
Notes: Each DOS session has a freeze count. This count starts at zero when the DOS session is created. Each ''VDHFreezeVDM''call adds one to this count. Each ''VDHThawVDM''call subtracts one from this count. The DOS session is frozen when the freeze count is 1 (one) or greater. The DOS session is thawed when the freeze count is 0 (zero). This allows multiple virtual device drivers to perform freeze and thaw operations without inadvertently causing the DOS session to run. If this count exceeds MAX_FREEZE_COUNT, ''VDHFreezeVDM''returns VDHERR_FROZEN_LIMIT.
 
 
 
 
 
=== VDHFreezeVDM - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetCodePageFont ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  the  address  of  the  code  page  font
information ,  if  code  page  support  is  active  and  a  font  is  available
for  the  given  character  cell  dimensions .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetCodePageFont : NEAR
CellWidth      DD  ?      ;    Width  of  character  cells ,  in  pels
CellHeight    DD  ?      ;    Height  of  character  cells ,  in  pels
FontAddress    DD  ?      ;    Address  where  font  table  addresses  will  be  copied
 
PUSH      CellWidth      ;    Push  CellWidth
PUSH      CellHeight    ;    Push  CellHeight
PUSH      FontAddress    ;    Push  FontAddress
 
CALL      VDHGetCodePageFont      ;  Call  the  function </pre>
 
 
 
 
=== VDHGetCodePageFont - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  the  address  of  the  code  page  font
information ,  if  code  page  support  is  active  and  a  font  is  available
for  the  given  character  cell  dimensions .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetCodePageFont : NEAR
CellWidth      DD  ?      ;    Width  of  character  cells ,  in  pels
CellHeight    DD  ?      ;    Height  of  character  cells ,  in  pels
FontAddress    DD  ?      ;    Address  where  font  table  addresses  will  be  copied
 
PUSH      CellWidth      ;    Push  CellWidth
PUSH      CellHeight    ;    Push  CellHeight
PUSH      FontAddress    ;    Push  FontAddress
 
CALL      VDHGetCodePageFont      ;  Call  the  function </pre>
 
 
 
 
=== VDHGetCodePageFont Parameter - CellWidth ===
 
'''CellWidth'''(DD) Width of character cells, measured in pels.
 
 
 
 
 
=== VDHGetCodePageFont Parameter - CellHeight ===
 
'''CellHeight'''(DD) Height of character cells, measured in pels.
 
 
 
 
 
=== VDHGetCodePageFont Parameter - FontAddress ===
 
'''FontAddress'''(DD) Address to which font table addresses will be copied.
 
 
 
 
 
=== VDHGetCodePageFont Return Value - rc ===
 
Success If the function is successful, it returns the size of the font table in bytes.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHGetCodePageFont - Parameters ===
 
'''CellWidth'''(DD) Width of character cells, measured in pels.
 
'''CellHeight'''(DD) Height of character cells, measured in pels.
 
'''FontAddress'''(DD) Address to which font table addresses will be copied.
 
 
 
 
 
=== VDHGetCodePageFont - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: If this function was called on behalf of the terminating DOS session, ''VDHReleaseCodePageFont''must be called to release the fonts.
 
Notes: System memory can be allocated to hold the font, especially if it is a merged font (that is, merged from two separate font tables). When the virtual device driver is finished with the font, it must call ''VDHReleaseCodePageFont''.
 
 
 
 
 
=== VDHGetCodePageFont - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetDirtyPageInfo ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  a  bit  vector  for  the  dirty  pages  of  a  specified
DOS  session  for  a  specified  range  of  pages .
The  dirty  bits  for  the  range  are  reset .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetDirtyPageInfo : NEAR
VDMHandle          DD  ?      ;    Handle  to  the  DOS  session  that  owns  the  object
StartingAddress    DD  ?      ;    Address  to  start  the  scan
PageRange          DD  ?      ;    Range  of  pages  to  scan
 
PUSH      VDMHandle          ;    Push  VDMHandle
PUSH      StartingAddress    ;    Push  StartingAddress
PUSH      PageRange          ;    Push  PageRange
 
CALL      VDHGetDirtyPageInfo          ;  Call  the  function </pre>
 
 
 
 
=== VDHGetDirtyPageInfo - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  a  bit  vector  for  the  dirty  pages  of  a  specified
DOS  session  for  a  specified  range  of  pages .
The  dirty  bits  for  the  range  are  reset .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetDirtyPageInfo : NEAR
VDMHandle          DD  ?      ;    Handle  to  the  DOS  session  that  owns  the  object
StartingAddress    DD  ?      ;    Address  to  start  the  scan
PageRange          DD  ?      ;    Range  of  pages  to  scan
 
PUSH      VDMHandle          ;    Push  VDMHandle
PUSH      StartingAddress    ;    Push  StartingAddress
PUSH      PageRange          ;    Push  PageRange
 
CALL      VDHGetDirtyPageInfo          ;  Call  the  function </pre>
 
 
 
 
=== VDHGetDirtyPageInfo Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) Handle to the DOS session that owns the object. A 0 (zero) value indicates the current DOS session.
 
 
 
 
 
=== VDHGetDirtyPageInfo Parameter - StartingAddress ===
 
'''StartingAddress'''(DD) Starting address of the range of pages to scan.
 
 
 
 
 
=== VDHGetDirtyPageInfo Parameter - PageRange ===
 
'''PageRange'''(DD) Range (number of pages) to scan. Maximum allowed is 32.
 
 
 
 
 
=== VDHGetDirtyPageInfo Return Value - rc ===
 
Success If the function is successful, it returns the bit vector. The low- order bit (that is, bit 0, the rightmost bit) is the dirty bit for the first page scanned. Bit 1 (from the right) is the dirty bit for the next page, and so forth for all the pages scanned.
 
Failure If any of the input parameters are invalid, a system halt occurs.
 
 
 
 
 
=== VDHGetDirtyPageInfo - Parameters ===
 
'''VDMHandle'''(DD) Handle to the DOS session that owns the object. A 0 (zero) value indicates the current DOS session.
 
'''StartingAddress'''(DD) Starting address of the range of pages to scan.
 
'''PageRange'''(DD) Range (number of pages) to scan. Maximum allowed is 32.
 
 
 
 
 
=== VDHGetDirtyPageInfo - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: The virtual dirty bits remain set until cleared by this function, regardless of the swapping activity that has occurred. The actual dirty bits in the page tables are reset whenever a page is swapped to the swap device and brought back into memory. This function is valid only for linear addresses up to 110000H (1MB+64KB) in a DOS session.
 
 
 
 
 
=== VDHGetDirtyPageInfo - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetError ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  the  error  code  from  the  last  virtual  DevHlp
service  called .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetError : NEAR
    DD  ?
 
PUSH          ;    Push
 
CALL      VDHGet ;  Call  the  function </pre>
 
 
 
 
=== VDHGetError - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  the  error  code  from  the  last  virtual  DevHlp
service  called .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetError : NEAR
    DD  ?
 
PUSH          ;    Push
 
CALL      VDHGet ;  Call  the  function </pre>
 
 
 
 
=== VDHGetError Parameter - ===
 
(DD) None.
 
 
 
 
 
=== VDHGetError Return Value - rc ===
 
Success If the function is successful, it returns the error code.
 
Failure If the function fails, it returns 0, indicating that the last virtual DevHlp call did not have an error.
 
 
 
 
 
=== VDHGetError - Parameters ===
 
(DD) None.
 
 
 
 
 
=== VDHGetError - Purpose ===
 
Context Issues: This function can be called in any context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: The return value is guaranteed to be valid as long as the virtual device driver does not block or yield between the virtual DevHlp service that failed and the call to ''VDHGetError''. ''VDHGetError''and ''VDHSetError''work at hardware interrupt time. Each level of interrupt nesting (where task time is Level 0) has a separate error code variable.
 
 
 
 
 
=== VDHGetError - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetFlags ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  gets  the  DOS  session ' s  EFlags  Register .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetFlags : NEAR
ulFlagsAddr    DD  ?      ;    DOS  session  flag  address .
 
PUSH      ulFlagsAddr    ;    Push  ulFlagsAddr
 
CALL      VDHGetFlags      ;  Call  the  function </pre>
 
 
 
 
=== VDHGetFlags - Format ===
 
 
 
<pre class="western">/*
 
This  function  gets  the  DOS  session ' s  EFlags  Register .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetFlags : NEAR
ulFlagsAddr    DD  ?      ;    DOS  session  flag  address .
 
PUSH      ulFlagsAddr    ;    Push  ulFlagsAddr
 
CALL      VDHGetFlags      ;  Call  the  function </pre>
 
 
 
 
=== VDHGetFlags Parameter - ulFlagsAddr ===
 
'''ulFlagsAddr'''(DD) Address of the ULONG in which the EFLAGs value is to be returned.
 
 
 
 
 
=== VDHGetFlags Return Value - ===
 
None.
 
 
 
 
 
=== VDHGetFlags - Parameters ===
 
'''ulFlagsAddr'''(DD) Address of the ULONG in which the EFLAGs value is to be returned.
 
 
 
 
 
=== VDHGetFlags - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Virtual device drivers must use this interface instead of the client register frame pointer to change the DOS session's flags. Changes to the interrupt flag and the I/O Privilege Level (IOPL) field must be under the control of 8086 emulation so that ''VDHArmSTIHook''works correctly.
 
Getting the Interrupt Flag (IF) must be under 8086 emulation control due to virtual mode extensions and DPMI.
 
 
 
 
 
=== VDHGetFlags - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetSelBase ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  the  base  address  for  a  Local  Descriptor  Table
( LDT )  selector .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetSelBase : NEAR
Selector        DW  ?      ;    LDT  selector
pBasePointer    DD  ?      ;    Pointer  for  returned  address
 
PUSH      Selector        ;    Push  Selector
PUSH      pBasePointer    ;    Push  pBasePointer
 
CALL      VDHGetSelBase      ;  Call  the  function </pre>
 
 
 
 
=== VDHGetSelBase - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  the  base  address  for  a  Local  Descriptor  Table
( LDT )  selector .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetSelBase : NEAR
Selector        DW  ?      ;    LDT  selector
pBasePointer    DD  ?      ;    Pointer  for  returned  address
 
PUSH      Selector        ;    Push  Selector
PUSH      pBasePointer    ;    Push  pBasePointer
 
CALL      VDHGetSelBase      ;  Call  the  function </pre>
 
 
 
 
=== VDHGetSelBase Parameter - Selector ===
 
'''Selector'''(DW) LDT Selector.
 
 
 
 
 
=== VDHGetSelBase Parameter - pBasePointer ===
 
'''pBasePointer'''(DD) Pointer for returned address.
 
 
 
 
 
=== VDHGetSelBase Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value. The base address is returned in the variable pointed to by ''pBasePointer''.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHGetSelBase - Parameters ===
 
'''Selector'''(DW) LDT Selector.
 
'''pBasePointer'''(DD) Pointer for returned address.
 
 
 
 
 
=== VDHGetSelBase - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Error checking is performed only to ensure that the selector is allocated.
 
 
 
 
 
=== VDHGetSelBase - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetVPMExcept ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  gets  the  current  value  from  the
protected - mode  exception  table .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetVPMExcept : NEAR
Vector                    DD  ?      ;    Exception  vector  number
pHandlerAddressPointer    DD  ?      ;    Pointer  to  put  handler  address
pFlag                      DD  ?      ;    Pointer  to  a  flag  variable
 
PUSH      Vector                    ;    Push  Vector
PUSH      pHandlerAddressPointer    ;    Push  pHandlerAddressPointer
PUSH      pFlag                      ;    Push  pFlag
 
CALL      VDHGetVPMExcept                  ;  Call  the  function </pre>
 
 
 
 
=== VDHGetVPMExcept - Format ===
 
 
 
<pre class="western">/*
 
This  function  gets  the  current  value  from  the
protected - mode  exception  table .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetVPMExcept : NEAR
Vector                    DD  ?      ;    Exception  vector  number
pHandlerAddressPointer    DD  ?      ;    Pointer  to  put  handler  address
pFlag                      DD  ?      ;    Pointer  to  a  flag  variable
 
PUSH      Vector                    ;    Push  Vector
PUSH      pHandlerAddressPointer    ;    Push  pHandlerAddressPointer
PUSH      pFlag                      ;    Push  pFlag
 
CALL      VDHGetVPMExcept                  ;  Call  the  function </pre>
 
 
 
 
=== VDHGetVPMExcept Parameter - Vector ===
 
'''Vector'''(DD) Exception vector number (''0''-1FH).
 
 
 
 
 
=== VDHGetVPMExcept Parameter - pHandlerAddressPointer ===
 
'''pHandlerAddressPointer'''(DD) Pointer to put handler address.
 
 
 
 
 
=== VDHGetVPMExcept Parameter - pFlag ===
 
'''pFlag'''(DD) Pointer to a flag variable for returning the flag value. Possible values are:
 
VPMXCPT32 A 32-bit handler was registered. <br />VPMXCPT_REFLECT The exception is reflected back to a V86-mode handler.
 
 
 
 
 
=== VDHGetVPMExcept Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0.
 
 
 
 
 
=== VDHGetVPMExcept - Parameters ===
 
'''Vector'''(DD) Exception vector number (''0''-1FH).
 
'''pHandlerAddressPointer'''(DD) Pointer to put handler address.
 
'''pFlag'''(DD) Pointer to a flag variable for returning the flag value. Possible values are:
 
VPMXCPT32 A 32-bit handler was registered. <br />VPMXCPT_REFLECT The exception is reflected back to a V86-mode handler.
 
 
 
 
 
=== VDHGetVPMExcept - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: There must be a DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHGetVPMExcept - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHGetVPMIntVector ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  gets  the  application  Ring  3
protected - mode  interrupt  handler .
This  service  is  used  only  for  DOS  Protected - Mode  Interface  ( DPMI )  support .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetVPMIntVector : NEAR
Vector                    DD  ?      ;    Interrupt  vector  number
HandlerAddressPointer    DD  ?      ;    Pointer  for  return  of  handler  address
 
PUSH      Vector                    ;    Push  Vector
PUSH      HandlerAddressPointer    ;    Push  HandlerAddressPointer
 
CALL      VDHGetVPMIntVector                ;  Call  the  function </pre>
 
 
 
 
=== VDHGetVPMIntVector - Format ===
 
 
 
<pre class="western">/*
 
This  function  gets  the  application  Ring  3
protected - mode  interrupt  handler .
This  service  is  used  only  for  DOS  Protected - Mode  Interface  ( DPMI )  support .
* /
 
include  mvdm . inc
 
EXTERN    VDHGetVPMIntVector : NEAR
Vector                    DD  ?      ;    Interrupt  vector  number
HandlerAddressPointer    DD  ?      ;    Pointer  for  return  of  handler  address
 
PUSH      Vector                    ;    Push  Vector
PUSH      HandlerAddressPointer    ;    Push  HandlerAddressPointer
 
CALL      VDHGetVPMIntVector                ;  Call  the  function </pre>
 
 
 
 
=== VDHGetVPMIntVector Parameter - Vector ===
 
'''Vector'''(DD) Interrupt vector number.
 
 
 
 
 
=== VDHGetVPMIntVector Parameter - HandlerAddressPointer ===
 
'''HandlerAddressPointer'''(DD) Pointer for return of the handler address.
 
 
 
 
 
=== VDHGetVPMIntVector Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0.
 
 
 
 
 
=== VDHGetVPMIntVector - Parameters ===
 
'''Vector'''(DD) Interrupt vector number.
 
'''HandlerAddressPointer'''(DD) Pointer for return of the handler address.
 
 
 
 
 
=== VDHGetVPMIntVector - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
'''Note:'''There must be a DPMI client in the DOS session before calling this function.
 
 
 
 
 
=== VDHGetVPMIntVector - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHHaltSystem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  causes  a  system  halt .
* /
 
include  mvdm . inc
 
EXTERN    VDHHaltSystem : NEAR
                DD  ?
 
PUSH                      ;    Push
 
CALL      VDHHaltSystem      ;  Call  the  function </pre>
 
 
 
 
=== VDHHaltSystem - Format ===
 
 
 
<pre class="western">/*
 
This  function  causes  a  system  halt .
* /
 
include  mvdm . inc
 
EXTERN    VDHHaltSystem : NEAR
                DD  ?
 
PUSH                      ;    Push
 
CALL      VDHHaltSystem      ;  Call  the  function </pre>
 
 
 
 
=== VDHHaltSystem Parameter - ===
 
(DD) None.
 
 
 
 
 
=== VDHHaltSystem Return Value - ===
 
None.
 
 
 
 
 
=== VDHHaltSystem - Parameters ===
 
(DD) None.
 
 
 
 
 
=== VDHHaltSystem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Calling ''VDHHaltSystem''is an extremely drastic action. Calling ''VDHPopup''and ''VDHKillVDM''is the preferred method for handling a problem. ''VDHHaltSystem''is used only if the virtual device driver is certain that the entire multiple DOS session environment is inoperable. In general, this function is used only by a base virtual device driver (for example, the virtual video device driver or virtual keyboard device driver), whose absence would render the multiple DOS session environment unusable. ''VDHPopup''is called prior to ''VDHHaltSystem''to tell the user what has happened.
 
 
 
 
 
=== VDHHaltSystem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHHandleFromPID ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  the  DOS  session  handle  for  a  given  Process  ID .
* /
 
include  mvdm . inc
 
EXTERN    VDHHandleFromPID : NEAR
ProcessID    DW  ?      ;    A  DOS  session  process  ID
 
PUSH      ProcessID    ;    Push  ProcessID
 
CALL      VDHHandleFromPID    ;  Call  the  function </pre>
 
 
 
 
=== VDHHandleFromPID - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  the  DOS  session  handle  for  a  given  Process  ID .
* /
 
include  mvdm . inc
 
EXTERN    VDHHandleFromPID : NEAR
ProcessID    DW  ?      ;    A  DOS  session  process  ID
 
PUSH      ProcessID    ;    Push  ProcessID
 
CALL      VDHHandleFromPID    ;  Call  the  function </pre>
 
 
 
 
=== VDHHandleFromPID Parameter - ProcessID ===
 
'''ProcessID'''(DW) A DOS session Process ID.
 
 
 
 
 
=== VDHHandleFromPID Return Value - rc ===
 
Success If the function is successful, it returns the DOS session handle for the Process ID.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHHandleFromPID - Parameters ===
 
'''ProcessID'''(DW) A DOS session Process ID.
 
 
 
 
 
=== VDHHandleFromPID - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHHandleFromPID - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHHandleFromSGID ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  determines  the  DOS  session  handle  given  the  Screen
Group  ID .
* /
 
include  mvdm . inc
 
EXTERN    VDHHandleFromSGID : NEAR
ScreenGroupID    DW  ?      ;    Screen  Group  ID
 
PUSH      ScreenGroupID    ;    Push  ScreenGroupID
 
CALL      VDHHandleFromSGID        ;  Call  the  function </pre>
 
 
 
 
=== VDHHandleFromSGID - Format ===
 
 
 
<pre class="western">/*
 
This  function  determines  the  DOS  session  handle  given  the  Screen
Group  ID .
* /
 
include  mvdm . inc
 
EXTERN    VDHHandleFromSGID : NEAR
ScreenGroupID    DW  ?      ;    Screen  Group  ID
 
PUSH      ScreenGroupID    ;    Push  ScreenGroupID
 
CALL      VDHHandleFromSGID        ;  Call  the  function </pre>
 
 
 
 
=== VDHHandleFromSGID Parameter - ScreenGroupID ===
 
'''ScreenGroupID'''(DW) Screen Group ID.
 
 
 
 
 
=== VDHHandleFromSGID Return Value - rc ===
 
Success If the function is successful, it returns a handle to the DOS session that was given the Screen Group ID.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHHandleFromSGID - Parameters ===
 
'''ScreenGroupID'''(DW) Screen Group ID.
 
 
 
 
 
=== VDHHandleFromSGID - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHHandleFromSGID - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHInstallFaultHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  sets  a  page  fault  handler  for  a  region  of  linear
address  space .
The  page  fault  handler  receives  control  when  a  DOS  session
touches  a  page  in  a  reserved  region  that  was  invalidated  by  VDHMapPages .
The  handler  does  not  get  control  if  the  page  was  indicated
&quot; not  present &quot;  by  the  Page  Manager .
* /
 
include  mvdm . inc
 
EXTERN    VDHInstallFaultHook : NEAR
VDMHandle                  DD  ?      ;    DOS  session  handle ;  0  =  current  DOS  session
StartingAddress          DD  ?      ;    Starting  linear  address
Pages                      DD  ?      ;    Number  of  pages
PageFaultHandlerFcnPtr    DD  ?      ;    Page  fault  handler  function
OptionFlag                DD  ?      ;    Options  bit  flag
 
PUSH      VDMHandle                  ;    Push  VDMHandle
PUSH      StartingAddress          ;    Push  StartingAddress
PUSH      Pages                      ;    Push  Pages
PUSH      PageFaultHandlerFcnPtr    ;    Push  PageFaultHandlerFcnPtr
PUSH      OptionFlag                ;    Push  OptionFlag
 
CALL      VDHInstallFaultHook                  ;  Call  the  function </pre>
 
 
 
 
=== VDHInstallFaultHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  sets  a  page  fault  handler  for  a  region  of  linear
address  space .
The  page  fault  handler  receives  control  when  a  DOS  session
touches  a  page  in  a  reserved  region  that  was  invalidated  by  VDHMapPages .
The  handler  does  not  get  control  if  the  page  was  indicated
&quot; not  present &quot;  by  the  Page  Manager .
* /
 
include  mvdm . inc
 
EXTERN    VDHInstallFaultHook : NEAR
VDMHandle                  DD  ?      ;    DOS  session  handle ;  0  =  current  DOS  session
StartingAddress          DD  ?      ;    Starting  linear  address
Pages                      DD  ?      ;    Number  of  pages
PageFaultHandlerFcnPtr    DD  ?      ;    Page  fault  handler  function
OptionFlag                DD  ?      ;    Options  bit  flag
 
PUSH      VDMHandle                  ;    Push  VDMHandle
PUSH      StartingAddress          ;    Push  StartingAddress
PUSH      Pages                      ;    Push  Pages
PUSH      PageFaultHandlerFcnPtr    ;    Push  PageFaultHandlerFcnPtr
PUSH      OptionFlag                ;    Push  OptionFlag
 
CALL      VDHInstallFaultHook                  ;  Call  the  function </pre>
 
 
 
 
=== VDHInstallFaultHook Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) DOS session handle. If the parameter contains a 0 (zero), use the currently active DOS session.
 
 
 
 
 
=== VDHInstallFaultHook Parameter - StartingAddress ===
 
'''StartingAddress'''(DD) Starting linear address.
 
 
 
 
 
=== VDHInstallFaultHook Parameter - Pages ===
 
'''Pages'''(DD) Number of pages.
 
 
 
 
 
=== VDHInstallFaultHook Parameter - PageFaultHandlerFcnPtr ===
 
'''PageFaultHandlerFcnPtr'''(DD) Page fault handler function.
 
The PageFaultHandlerFcnPtr function pointer contains the address of a function with the following interface:
 
<pre class="western">PageFaultHandler  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pVDM - Address of the page in which fault occurred
;    EXIT  None
;
; CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHInstallFaultHook Parameter - OptionFlag ===
 
'''OptionFlag'''(DD) Options bit flag.
 
Possible value:
 
VDHIFH_ADDR If set, pVDM is a byte-granular address. Otherwise, pVDM is a page-granular address.
 
 
 
 
 
=== VDHInstallFaultHook Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If any of the input parameters are invalid, a system halt occurs.
 
 
 
 
 
=== VDHInstallFaultHook - Parameters ===
 
'''VDMHandle'''(DD) DOS session handle. If the parameter contains a 0 (zero), use the currently active DOS session.
 
'''StartingAddress'''(DD) Starting linear address.
 
'''Pages'''(DD) Number of pages.
 
'''PageFaultHandlerFcnPtr'''(DD) Page fault handler function.
 
The PageFaultHandlerFcnPtr function pointer contains the address of a function with the following interface:
 
<pre class="western">PageFaultHandler  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pVDM - Address of the page in which fault occurred
;    EXIT  None
;
; CONTEXT  DOS session-task</pre>
 
 
'''OptionFlag'''(DD) Options bit flag.
 
Possible value:
 
VDHIFH_ADDR If set, pVDM is a byte-granular address. Otherwise, pVDM is a page-granular address.
 
 
 
 
 
=== VDHInstallFaultHook - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: Any fault hooks for the terminating DOS session must be released by using VDHRemoveFaultHook.
 
Notes: In order for the fault handler to terminate the DOS session, it must call VDHKillVDM and return. Page fault hooks are stored on a per-DOS session basis.
 
 
 
 
 
=== VDHInstallFaultHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHInstallIntHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  sets  a  handler  for  a  V86  interrupt .
The  virtual  device  driver ' s  interrupt  handler  gets  control  after  any  subsequently
hooked  DOS  interrupt  handlers .
* /
 
include  mvdm . inc
 
EXTERN    VDHInstallIntHook : NEAR
Reserved      DD  ?      ;    Reserved ;  must  be  set  to  0
Vector        DD  ?      ;    Number  of  the  interrupt  vector  to  hook
HookFcn      DD  ?      ;    Address  of  the  hook  routine
OptionFlag    DD  ?      ;    Interface  options  flag
 
PUSH      Reserved      ;    Push  Reserved
PUSH      Vector        ;    Push  Vector
PUSH      HookFcn      ;    Push  HookFcn
PUSH      OptionFlag    ;    Push  OptionFlag
 
CALL      VDHInstallIntHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHInstallIntHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  sets  a  handler  for  a  V86  interrupt .
The  virtual  device  driver ' s  interrupt  handler  gets  control  after  any  subsequently
hooked  DOS  interrupt  handlers .
* /
 
include  mvdm . inc
 
EXTERN    VDHInstallIntHook : NEAR
Reserved      DD  ?      ;    Reserved ;  must  be  set  to  0
Vector        DD  ?      ;    Number  of  the  interrupt  vector  to  hook
HookFcn      DD  ?      ;    Address  of  the  hook  routine
OptionFlag    DD  ?      ;    Interface  options  flag
 
PUSH      Reserved      ;    Push  Reserved
PUSH      Vector        ;    Push  Vector
PUSH      HookFcn      ;    Push  HookFcn
PUSH      OptionFlag    ;    Push  OptionFlag
 
CALL      VDHInstallIntHook    ;  Call  the  function </pre>
 
 
 
 
=== VDHInstallIntHook Parameter - Reserved ===
 
'''Reserved'''(DD) Reserved. Must be set to 0.
 
 
 
 
 
=== VDHInstallIntHook Parameter - Vector ===
 
'''Vector'''(DD) Number of the interrupt vector to hook (0-255).
 
 
 
 
 
=== VDHInstallIntHook Parameter - HookFcn ===
 
'''HookFcn'''(DD) Address of the hook routine.
 
 
 
 
 
=== VDHInstallIntHook Parameter - OptionFlag ===
 
'''OptionFlag'''(DD) Interface options flag.
 
Possible values:
 
VDH_ASM_HOOK Use assembler language hook interface (for the assembler language interface refer to the function [[00583.htm|VDHInstallIOHook]]). Otherwise, use the calling convention in the function prototype VDHENTRY found in the MVDM .INC include file, which is included with the Toolkit.
 
VDH_PRE_HOOK If set, install handler as a pre-reflection hook; that is, call the hook routine before reflecting the interrupt to V86 mode.
 
C Language Interface for the interrupt hook routine:
 
<pre class="western"> HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  EBX - pcrf - Client register frame pointer
;    EXIT  If carry flag set, chain to next virtual device driver
;            If carry flag clear, don't chain to the next virtual
;            device driver
;    USES  EAX, ECX, EDX, FS, GS, Flags
;  CONTEXT  DOS Session-task</pre>
 
 
 
 
 
 
=== VDHInstallIntHook Return Value - rc ===
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''HookFcn''is invalid or if ''Vector''is out of range, a system halt occurs.
 
 
 
 
 
=== VDHInstallIntHook - Parameters ===
 
'''Reserved'''(DD) Reserved. Must be set to 0.
 
'''Vector'''(DD) Number of the interrupt vector to hook (0-255).
 
'''HookFcn'''(DD) Address of the hook routine.
 
'''OptionFlag'''(DD) Interface options flag.
 
Possible values:
 
VDH_ASM_HOOK Use assembler language hook interface (for the assembler language interface refer to the function [[00583.htm|VDHInstallIOHook]]). Otherwise, use the calling convention in the function prototype VDHENTRY found in the MVDM .INC include file, which is included with the Toolkit.
 
VDH_PRE_HOOK If set, install handler as a pre-reflection hook; that is, call the hook routine before reflecting the interrupt to V86 mode.
 
C Language Interface for the interrupt hook routine:
 
<pre class="western"> HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  EBX - pcrf - Client register frame pointer
;    EXIT  If carry flag set, chain to next virtual device driver
;            If carry flag clear, don't chain to the next virtual
;            device driver
;    USES  EAX, ECX, EDX, FS, GS, Flags
;  CONTEXT  DOS Session-task</pre>
 
 
 
 
 
 
=== VDHInstallIntHook - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function. Interrupt hooks are automatically removed during DOS session termination.
 
Notes: The effect of this service is per-DOS session; the software interrupt handler must be installed as each DOS session is created. The return value from the interrupt hook controls whether the next virtual device driver is chained to or not. An explicit ''VDHPopInt''is needed to remove the software interrupt (so that the ROM code is not executed).
 
 
 
 
 
=== VDHInstallIntHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHInstallIOHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  to  install  I / O  port  hooks .
* /
 
include  mvdm . inc
 
EXTERN    VDHInstallIOHook : NEAR
Reserved          DD  ?      ;    Reserved ;  must  be  set  to  0
StartingPort      DD  ?      ;    Starting  port  number
NumPorts          DD  ?      ;    The  number  of  ports  from  the  starting  point
IOPortHookEntry    DD  ?      ;    Pointer  to  I / O  port  hook  entry
Flags              DD  ?      ;    Indicates  interface  and  trapping  options
 
PUSH      Reserved          ;    Push  Reserved
PUSH      StartingPort      ;    Push  StartingPort
PUSH      NumPorts          ;    Push  NumPorts
PUSH      IOPortHookEntry    ;    Push  IOPortHookEntry
PUSH      Flags              ;    Push  Flags
 
CALL      VDHInstallIOHook          ;  Call  the  function </pre>
 
 
 
 
=== VDHInstallIOHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  to  install  I / O  port  hooks .
* /
 
include  mvdm . inc
 
EXTERN    VDHInstallIOHook : NEAR
Reserved          DD  ?      ;    Reserved ;  must  be  set  to  0
StartingPort      DD  ?      ;    Starting  port  number
NumPorts          DD  ?      ;    The  number  of  ports  from  the  starting  point
IOPortHookEntry    DD  ?      ;    Pointer  to  I / O  port  hook  entry
Flags              DD  ?      ;    Indicates  interface  and  trapping  options
 
PUSH      Reserved          ;    Push  Reserved
PUSH      StartingPort      ;    Push  StartingPort
PUSH      NumPorts          ;    Push  NumPorts
PUSH      IOPortHookEntry    ;    Push  IOPortHookEntry
PUSH      Flags              ;    Push  Flags
 
CALL      VDHInstallIOHook          ;  Call  the  function </pre>
 
 
 
 
=== VDHInstallIOHook Parameter - Reserved ===
 
'''Reserved'''(DD) Reserved. Must be set to 0 (zero).
 
 
 
 
 
=== VDHInstallIOHook Parameter - StartingPort ===
 
'''StartingPort'''(DD) Number of the starting port.
 
 
 
 
 
=== VDHInstallIOHook Parameter - NumPorts ===
 
'''NumPorts'''(DD) The number of ports from the starting port.
 
 
 
 
 
=== VDHInstallIOHook Parameter - IOPortHookEntry ===
 
'''IOPortHookEntry'''(DD) Pointer to I/O port hook entry.
 
 
 
 
 
=== VDHInstallIOHook Parameter - Flags ===
 
'''Flags'''(DD) Indicates interface and trapping options.
 
Possible values:
 
VDHIIH_ASM_HOOK Use assembler language hook interface (register-based). Otherwise, use a C hook interface (stack-based).
 
VDHIIH_ALWAYS_TRAP Always trap this range of addresses. The virtual device driver cannot call VDHSetIOHookState on any ports in the range.
 
VDHIIH_NO_SIMULATE Does not change WORD or other I/O handlers to simulation routines; allows WORD handlers for 1-port ranges.
 
VDHIIH_IGNORE Sets a system handler that does the following:
 
On WRITES: The OUT succeeds, but no actual I/O is performed. <br />On READS: The IN succeeds, and always returns -1 (all bits set to 1).
 
This is also the default behavior of unhooked ports. This behavior is compatible with the behavior of a machine when there is no hardware on a particular I/O address.
 
 
 
 
 
=== VDHInstallIOHook Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''IOPortHookEntry''is invalid, or if ''StartingPort''or ''NumPorts''are out of range, a system halt occurs.
 
 
 
 
 
=== VDHInstallIOHook - Parameters ===
 
'''Reserved'''(DD) Reserved. Must be set to 0 (zero).
 
'''StartingPort'''(DD) Number of the starting port.
 
'''NumPorts'''(DD) The number of ports from the starting port.
 
'''IOPortHookEntry'''(DD) Pointer to I/O port hook entry.
 
'''Flags'''(DD) Indicates interface and trapping options.
 
Possible values:
 
VDHIIH_ASM_HOOK Use assembler language hook interface (register-based). Otherwise, use a C hook interface (stack-based).
 
VDHIIH_ALWAYS_TRAP Always trap this range of addresses. The virtual device driver cannot call VDHSetIOHookState on any ports in the range.
 
VDHIIH_NO_SIMULATE Does not change WORD or other I/O handlers to simulation routines; allows WORD handlers for 1-port ranges.
 
VDHIIH_IGNORE Sets a system handler that does the following:
 
On WRITES: The OUT succeeds, but no actual I/O is performed. <br />On READS: The IN succeeds, and always returns -1 (all bits set to 1).
 
This is also the default behavior of unhooked ports. This behavior is compatible with the behavior of a machine when there is no hardware on a particular I/O address.
 
 
 
 
 
=== VDHInstallIOHook - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function. I/O hooks are automatically removed during DOS session termination.
 
Notes: This function installs I/O port trap handlers for a contiguous range of I/O addresses. Trapping is initially enabled for the specified ports. The I/O hook entry contains the handlers for each kind of I/O operation. If an entry in the table is NULL, that I/O type is simulated by using a lower I/O type (for example, WORD-I/O is simulated by performing two-byte I/O operations). I/O port hooks are kept on a per-DOS session basis; a virtual device driver generally installs I/O hooks at DOS session creation time.
 
VDHSetIOHookState can be used to enable or disable I/O trapping on a per- port, per-DOS session basis except when the VDHIIH_ALWAYS_TRAP option is specified. In this case, VDHSetIOHookState cannot be called on any port in the range for the current DOS session.
 
I/O hooks can take their parameters either from registers or the stack. High-performance hooks take register parameters (the I/O hook router is optimized for this case). Hooks with lower performance requirements take stack parameters, and therefore can be written in the C language.
 
WordInput, WordOutput and Other hooks can be NULL. In this case, the DOS Session Manager simulates these routines by using the ByteInput and ByteOutput routines. If the ByteInput or ByteOutput handlers are NULL, the DOS Session Manager uses default internal routines that do input and output to the hardware ports. This is most useful when a virtual device driver shadows the hardware state (by trapping OUT instructions) but does not care what is returned by IN instructions.
 
The client register frame (CRF) is updated as the instructions are simulated. For example, when the string I/O instructions are simulated, the client's EDI/ESI and ECX is incremented or decremented.
 
In a particular DOS session, a particular I/O port address can be hooked only by a single virtual device driver. If this function fails, no I/O hooks are installed.
 
The routing of I/O instructions to the supplied port hooks covers the specified range exactly. If an I/O instruction overlaps port address ranges hooked on separate VDHInstallIOHook calls, the instruction is simulated with smaller I/O operations to ensure that the hooks in each range are called correctly. For example, a virtual device driver that hooks 100H-103H , and installs a byte, WORD, and DWORD (other) handler would work as follows:
 
<pre class="western">    VDHInstallIOHook (reserved,0x100,4,&amp;iohA,NULL);</pre>
The I/O instructions to each address with the length indicated cause the following hooks to be called:
 
<pre class="western">/--------------------------------------------------------------\
|Address        |Length        |Hooks Called                  |
|---------------+---------------+------------------------------|
|  100          |  4          |iohA.Other(100,DWORD)        |
|---------------+---------------+------------------------------|
|  101          |  4          |iohA.Word(101) iohA.Byte(103) |
|---------------+---------------+------------------------------|
|  102          |  4          |iohA.Word(102)                |
|---------------+---------------+------------------------------|
|  103          |  4          |iohA.Byte(103)                |
\--------------------------------------------------------------/</pre>
VDHRemoveIOHook must be called with identical StartingPort and NumPorts in order to remove these I/O hooks. Port hooks cannot be removed for a subset of the range of ports hooked on the call to VDHInstallIOHook. If the IOPortHookEntry is in instance data, the address passed to VDHInstallIOHook must be the same address passed to VDHRemoveIOHook or VDHSetIOHookState.
 
Virtual device drivers hook ports in all cases, even if the desired behavior is to act as though direct port access were allowed. This keeps the I/O Permissions Map small. Only a port that requires high performance ( for example, a graphics card) is allowed to go straight through. The existence of such ports increases the size of the I/O Permissions Map in the Task State segment even if SetIOHookState is never called for them.
 
Interfaces for IOPortHookEntry are as follows:
 
<pre class="western">ioh STRUC
    ioh_pbihByteInput    DD  ?
    ioh_pbohByteOutput  DD  ?
    ioh_pwihWordInput    DD  ?
    ioh_pwohWordOutput  DD  ?
    ioh_pothOther        DD  ?
ioh ENDS</pre>
 
 
<pre class="western">ByteInput  PROC  NEAR
; PARAMETERS
;    ENTRY  - port - Port number
;          - pcrf - Client register frame pointer
;    EXIT  Data read returned in AL
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">ByteOutput  PROC  NEAR
; PARAMETERS
;    ENTRY  - bOutputData - Data to write
;          - port        - Port number
;          - pcrf        - Client register frame pointer
;    EXIT  None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">WordInput  PROC  NEAR
; PARAMETERS
;    ENTRY  - port - Port number
;          - pcrf - Client register frame pointer
;    EXIT  Data read returned in AX
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">WordOutput  PROC  NEAR
; PARAMETERS
;    ENTRY  - usOutputData - Data to write
;            - port        - Port number
;            - pcrf        - Client register frame pointer
;    EXIT  None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">OtherHook  PROC  NEAR
; PARAMETERS
;    ENTRY  EAX - ulOutputData        - Data for DWORD writes
;          [ESP + 16] - pulInputData  - Pointer to put input data
;                        (See NOTE, below)
;          EDX - port                - Port number
;          ECX - flType              - I/O type
;              IO_TYPE_SHIFT          - Shift for type
;              IO_TYPE_MASK          - Mask for type
;              IO_TYPE_INPUT          - If set input else output
;              IO_TYPE_BYTE          - If set byte else WORD/DWORD
;              IO_TYPE_DWORD
;              IO_TYPE_STRING
;              IO_TYPE_REVERSE
;              IO_TYPE_ADDR32
;              IO_TYPE_REP
;              IO_SEG_SHIFT          - Shift for SEG  field
;              IO_SEG_MASK      - Mask for SEG field
;              IO_SEG_CS
;              IO_SEG_SS
;              IO_SEG_ES
;              IO_SEG_FS
;              IO_SEG_GS
;          EBX - pcrf          - Client register frame pointer
;    EXIT  If assembly language hook,
;              EAX - Data from DWORD reads
;              If carry flag set, simulate the I/O operation
;              If carry flag clear, I/O is done
;          If C hook
;              *pulInputData - Data from DWORD reads
;              If returns 0 in EAX, simulate the I/O operation
;              If returns a non-zero value in EAX, I/O is done
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  DOS session-task
; NOTES    The ASM OtherHook hook does not need the pulInputData parameter
;          because it returns DWORD input values in EAX, with the
;          carry flag used to indicate done/simulate.
;          The C hook has to use EAX to return status, and so needs the
;          additional parameter.</pre>
 
 
 
 
=== VDHInstallIOHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHInstallUserHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  to  set  a  handler  for  a  specific  DOS  session  event .
* /
 
include  mvdm . inc
 
EXTERN    VDHInstallUserHook : NEAR
Event      DD  ?      ;    A  DOS  session  event  for  which  a  handler  is  installed
UserHook    DD  ?      ;    User ' s  handler  for  this  event
 
PUSH      Event      ;    Push  Event
PUSH      UserHook    ;    Push  UserHook
 
CALL      VDHInstallUserHook  ;  Call  the  function </pre>
 
 
 
 
=== VDHInstallUserHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  to  set  a  handler  for  a  specific  DOS  session  event .
* /
 
include  mvdm . inc
 
EXTERN    VDHInstallUserHook : NEAR
Event      DD  ?      ;    A  DOS  session  event  for  which  a  handler  is  installed
UserHook    DD  ?      ;    User ' s  handler  for  this  event
 
PUSH      Event      ;    Push  Event
PUSH      UserHook    ;    Push  UserHook
 
CALL      VDHInstallUserHook  ;  Call  the  function </pre>
 
 
 
 
=== VDHInstallUserHook Parameter - Event ===
 
'''Event'''(DD) A DOS session event (such as DOS session termination).
 
Possible values are:
 
VDD_EXIT DOS session support is shutting down <br />VDM_CREATE DOS session creation <br />VDM_TERMINATE DOS session termination <br />VDM_FOREGROUND DOS session to the foreground <br />VDM_BACKGROUND DOS session to the background <br />VDM_CREATE_DONE DOS session creation completed successfully <br />VDM_VDD_CREATE_DONE DOS session virtual device driver creation completed <br />VDM_PDB_DESTROY DOS Program Data Block (PDB) destroyed in DOS session <br />VDM_PDB_CHANGE PDB changed in DOS session <br />VDM_CODEPAGE_CHANGE Code page change event <br />VDM_TITLE_CHANGE DOS session title change event <br />VDM_MEMORY_MAPPED_IN Pages mapped into a DOS session (0 to 1MB+64KB) <br />VDM_MEMORY_UN_MAPPED Pages unmapped from a DOS session (0 to 1MB+64KB). <br />VDM_BEGIN_VPM_TASK Protected-mode task has started <br />VDM_END_VPM_TASK Protected-mode task has ended
 
The interfaces for the ''UserHook''handlers (depending on the event that is handled) are:
 
<pre class="western">pfnCreate  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT  SUCCESS  Return a non-zero value
;          FAILURE  Return 0
;                    DOS session creation fails; the DOS Session Manager calls
;                    all the VDM_TERMINATE hooks for all virtual
;                    device drivers that returned SUCCESS on this
;                    DOS session creation.
;
;
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">pfnTerminate  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session being terminated
;    EXIT  None
;
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">pfnForeground  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session coming to the foreground
;    EXIT  None
;
; CONTEXT  Task</pre>
 
 
<pre class="western">pfnBackground  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session going to the background
;    EXIT  None
;
; CONTEXT  Task</pre>
 
 
<pre class="western">pfnExit  PROC  NEAR
; PARAMETERS
;    ENTRY  None
;    EXIT  None
;
; CONTEXT  Initialization and Task</pre>
 
 
<pre class="western">pfnCreateDone  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT  None
;
; CONTEXT  DOS session creation</pre>
 
 
<pre class="western">pfnVDDCreateDone  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT  None
;
; CONTEXT  DOS session Creation</pre>
 
 
<pre class="western">pfnPDBDestroyed  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm    - Handle to DOS session
;          [ESP + 4] - segPDB  - V86 segment of terminating PDB
;    EXIT  None
;
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">pfnPDBSwitched  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm  - Handle to DOS session
;          [ESP + 4] - segPDB - V86 segment of new PDB
;    EXIT  None
;
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">pfnCodePageChanged  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - ulCodePage - New code page
;    EXIT  SUCCESS  Return a non-zero value in EAX
;          FAILURE  Return 0 in EAX
;                    An error is returned on the set code-page operation, but
;                    the rest of the device-code-page handlers are called.
;
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">pfnVDMTitleChange  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pszTitle - new DOS session Title
;    EXIT  SUCCESS  Return a non-zero value in EAX
;          FAILURE  Return 0 in EAX
;
; CONTEXT  DOS session-task
; NOTES    1. This event is called for both full screen and windowed DOS session.
;          2. If pszTitle is NULL, the virtual device driver should treat it
;              as the DOS session's default and original title.
;          3. Ideally there should be only one virtual device driver for this
;              hook, but this is not a restriction.  One of the virtual device
;              drivers registered is responsible for putting the title.  Only
;              this virtual device driver returns a non-zero value, all others
;              return 0.</pre>
 
 
<pre class="western">pfnMemoryMappedIn  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - hvdm  - Handle to DOS session
;          [ESP + 12] - page  - Page address
;          [ESP +  8] - cpages - Number of pages mapped in from
;                            the starting page address
;          [ESP +  4] - fl    - Type of mapping, (see VDHMapPages)
;    EXIT  SUCCESS  Return a non-zero value in EAX
;          FAILURE  Return 0 in EAX
;
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">pfnMemoryUnMapped  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - hvdm  - Handle to DOS session
;          [ESP + 12] - page  - Page address
;          [ESP +  8] - cpages - Number of pages unmapped from
;                                                    the starting page address
;          [ESP +  4] - fl    - Type of mapping, (see VDHMapPages)
;    EXIT  SUCCESS  Return a non-zero value in EAX
;          FAILURE  Return 0 in EAX
;
; CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHInstallUserHook Parameter - UserHook ===
 
'''UserHook'''(DD) A user-defined handler for the event.
 
 
 
 
 
=== VDHInstallUserHook Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, an invalid input parameter or a kernel heap overflow (that is, if the system runs out of memory) causes a system halt.
 
 
 
 
 
=== VDHInstallUserHook - Parameters ===
 
'''Event'''(DD) A DOS session event (such as DOS session termination).
 
Possible values are:
 
VDD_EXIT DOS session support is shutting down <br />VDM_CREATE DOS session creation <br />VDM_TERMINATE DOS session termination <br />VDM_FOREGROUND DOS session to the foreground <br />VDM_BACKGROUND DOS session to the background <br />VDM_CREATE_DONE DOS session creation completed successfully <br />VDM_VDD_CREATE_DONE DOS session virtual device driver creation completed <br />VDM_PDB_DESTROY DOS Program Data Block (PDB) destroyed in DOS session <br />VDM_PDB_CHANGE PDB changed in DOS session <br />VDM_CODEPAGE_CHANGE Code page change event <br />VDM_TITLE_CHANGE DOS session title change event <br />VDM_MEMORY_MAPPED_IN Pages mapped into a DOS session (0 to 1MB+64KB) <br />VDM_MEMORY_UN_MAPPED Pages unmapped from a DOS session (0 to 1MB+64KB). <br />VDM_BEGIN_VPM_TASK Protected-mode task has started <br />VDM_END_VPM_TASK Protected-mode task has ended
 
The interfaces for the ''UserHook''handlers (depending on the event that is handled) are:
 
<pre class="western">pfnCreate  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT  SUCCESS  Return a non-zero value
;          FAILURE  Return 0
;                    DOS session creation fails; the DOS Session Manager calls
;                    all the VDM_TERMINATE hooks for all virtual
;                    device drivers that returned SUCCESS on this
;                    DOS session creation.
;
;
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">pfnTerminate  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session being terminated
;    EXIT  None
;
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">pfnForeground  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session coming to the foreground
;    EXIT  None
;
; CONTEXT  Task</pre>
 
 
<pre class="western">pfnBackground  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session going to the background
;    EXIT  None
;
; CONTEXT  Task</pre>
 
 
<pre class="western">pfnExit  PROC  NEAR
; PARAMETERS
;    ENTRY  None
;    EXIT  None
;
; CONTEXT  Initialization and Task</pre>
 
 
<pre class="western">pfnCreateDone  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT  None
;
; CONTEXT  DOS session creation</pre>
 
 
<pre class="western">pfnVDDCreateDone  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT  None
;
; CONTEXT  DOS session Creation</pre>
 
 
<pre class="western">pfnPDBDestroyed  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm    - Handle to DOS session
;          [ESP + 4] - segPDB  - V86 segment of terminating PDB
;    EXIT  None
;
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">pfnPDBSwitched  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm  - Handle to DOS session
;          [ESP + 4] - segPDB - V86 segment of new PDB
;    EXIT  None
;
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">pfnCodePageChanged  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - ulCodePage - New code page
;    EXIT  SUCCESS  Return a non-zero value in EAX
;          FAILURE  Return 0 in EAX
;                    An error is returned on the set code-page operation, but
;                    the rest of the device-code-page handlers are called.
;
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">pfnVDMTitleChange  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pszTitle - new DOS session Title
;    EXIT  SUCCESS  Return a non-zero value in EAX
;          FAILURE  Return 0 in EAX
;
; CONTEXT  DOS session-task
; NOTES    1. This event is called for both full screen and windowed DOS session.
;          2. If pszTitle is NULL, the virtual device driver should treat it
;              as the DOS session's default and original title.
;          3. Ideally there should be only one virtual device driver for this
;              hook, but this is not a restriction.  One of the virtual device
;              drivers registered is responsible for putting the title.  Only
;              this virtual device driver returns a non-zero value, all others
;              return 0.</pre>
 
 
<pre class="western">pfnMemoryMappedIn  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - hvdm  - Handle to DOS session
;          [ESP + 12] - page  - Page address
;          [ESP +  8] - cpages - Number of pages mapped in from
;                            the starting page address
;          [ESP +  4] - fl    - Type of mapping, (see VDHMapPages)
;    EXIT  SUCCESS  Return a non-zero value in EAX
;          FAILURE  Return 0 in EAX
;
; CONTEXT  DOS session-task</pre>
 
 
<pre class="western">pfnMemoryUnMapped  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - hvdm  - Handle to DOS session
;          [ESP + 12] - page  - Page address
;          [ESP +  8] - cpages - Number of pages unmapped from
;                                                    the starting page address
;          [ESP +  4] - fl    - Type of mapping, (see VDHMapPages)
;    EXIT  SUCCESS  Return a non-zero value in EAX
;          FAILURE  Return 0 in EAX
;
; CONTEXT  DOS session-task</pre>
 
 
'''UserHook'''(DD) A user-defined handler for the event.
 
 
 
 
 
=== VDHInstallUserHook - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Sessions Terminations: The VDM_TERMINATE hook is called at DOS session termination. In the case of a partially created DOS session, the VDM_ TERMINATE handler is called only if all the registered VDM_CREATE handlers are called successfully. Partially created DOS sessions might occur when, for example, the ''Create_Handler''for Virtual Device Driver A returned successfully, but the ''Create_Handler''for Virtual Device Driver B failed. In this case, the ''Terminate_Handler''for Virtual Device Driver A will not be called. This should be taken into consideration when deciding what to do in a ''Create_Handler''and a ''Create_Done_Handler''.
 
 
 
 
 
=== VDHInstallUserHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHIsVDMFrozen ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  the  freeze  state  of  a  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHIsVDMFrozen : NEAR
VDMHandle    DD  ?      ;    Handle  to  the  DOS  session
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHIsVDMFrozen    ;  Call  the  function </pre>
 
 
 
 
=== VDHIsVDMFrozen - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  the  freeze  state  of  a  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHIsVDMFrozen : NEAR
VDMHandle    DD  ?      ;    Handle  to  the  DOS  session
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHIsVDMFrozen    ;  Call  the  function </pre>
 
 
 
 
=== VDHIsVDMFrozen Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) Handle to the DOS session in question.
 
 
 
 
 
=== VDHIsVDMFrozen Return Value - rc ===
 
Success If the DOS session is not frozen, the function returns 0 (zero). Otherwise, the function returns a nonzero value indicating the DOS session' s freeze count.
 
Failure If ''VDMHandle''is an invalid DOS session handle, a system halt occurs .
 
 
 
 
 
=== VDHIsVDMFrozen - Parameters ===
 
'''VDMHandle'''(DD) Handle to the DOS session in question.
 
 
 
 
 
=== VDHIsVDMFrozen - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: See [[00477.htm|VDHFreezeVDM]]for a full discussion of freeze counting.
 
 
 
 
 
=== VDHIsVDMFrozen - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHKillVDM ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  terminates  the  DOS  session  at  the  earliest
opportunity .
V86  code  is  no  longer  executed  in  the  context  of  the
terminated  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHKillVDM : NEAR
VDMHandle    DD  ?      ;    Handle  to  the  DOS  session  to  terminate
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHKillVDM    ;  Call  the  function </pre>
 
 
 
 
=== VDHKillVDM - Format ===
 
 
 
<pre class="western">/*
 
This  function  terminates  the  DOS  session  at  the  earliest
opportunity .
V86  code  is  no  longer  executed  in  the  context  of  the
terminated  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHKillVDM : NEAR
VDMHandle    DD  ?      ;    Handle  to  the  DOS  session  to  terminate
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHKillVDM    ;  Call  the  function </pre>
 
 
 
 
=== VDHKillVDM Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) Handle to the DOS session to terminate. A value of 0 (zero) indicates the current DOS session.
 
 
 
 
 
=== VDHKillVDM Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''VDMHandle''is not a valid DOS session handle, a system halt occurs.
 
 
 
 
 
=== VDHKillVDM - Parameters ===
 
'''VDMHandle'''(DD) Handle to the DOS session to terminate. A value of 0 (zero) indicates the current DOS session.
 
 
 
 
 
=== VDHKillVDM - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: When a DOS session is terminating, all virtual device drivers that registered a VDM_TERMINATE hook by using ''VDHInstallUserHook''are called.
 
Notes: This function sets a flag and returns. If the calling virtual device driver is in the context of the DOS session to be terminated, it must return to its caller in order for the termination to occur.
 
 
 
 
 
=== VDHKillVDM - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHLockMem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  verifies  that  a  specified  region  is  accessible  in  the
requested  manner ,  and  locks  the  memory  in  the  requested  manner .
* /
 
include  mvdm . inc
 
EXTERN    VDHLockMem : NEAR
StartingLinAddr    DD  ?      ;    Starting  address  of  region  in  user  process
NumBytes            DD  ?      ;    The  size  of  the  region  to  lock ,  in  bytes .
OptionFlag          DD  ?      ;    Access  option  flags
PagelistArrayPtr    DD  ?      ;    Pointer  to  array  of  VDHPageList _ s  structures
ArrayCountPtr      DD  ?      ;    Points  to  count  of  VDHPageList _ selements
 
PUSH      StartingLinAddr    ;    Push  StartingLinAddr
PUSH      NumBytes            ;    Push  NumBytes
PUSH      OptionFlag          ;    Push  OptionFlag
PUSH      PagelistArrayPtr    ;    Push  PagelistArrayPtr
PUSH      ArrayCountPtr      ;    Push  ArrayCountPtr
 
CALL      VDHLockMem          ;  Call  the  function </pre>
 
 
 
 
=== VDHLockMem - Format ===
 
 
 
<pre class="western">/*
 
This  function  verifies  that  a  specified  region  is  accessible  in  the
requested  manner ,  and  locks  the  memory  in  the  requested  manner .
* /
 
include  mvdm . inc
 
EXTERN    VDHLockMem : NEAR
StartingLinAddr    DD  ?      ;    Starting  address  of  region  in  user  process
NumBytes            DD  ?      ;    The  size  of  the  region  to  lock ,  in  bytes .
OptionFlag          DD  ?      ;    Access  option  flags
PagelistArrayPtr    DD  ?      ;    Pointer  to  array  of  VDHPageList _ s  structures
ArrayCountPtr      DD  ?      ;    Points  to  count  of  VDHPageList _ selements
 
PUSH      StartingLinAddr    ;    Push  StartingLinAddr
PUSH      NumBytes            ;    Push  NumBytes
PUSH      OptionFlag          ;    Push  OptionFlag
PUSH      PagelistArrayPtr    ;    Push  PagelistArrayPtr
PUSH      ArrayCountPtr      ;    Push  ArrayCountPtr
 
CALL      VDHLockMem          ;  Call  the  function </pre>
 
 
 
 
=== VDHLockMem Parameter - StartingLinAddr ===
 
'''StartingLinAddr'''(DD) Starting linear address of the region in the user process that is to be locked.
 
 
 
 
 
=== VDHLockMem Parameter - NumBytes ===
 
'''NumBytes'''(DD) Size in bytes of the region to lock.
 
 
 
 
 
=== VDHLockMem Parameter - OptionFlag ===
 
'''OptionFlag'''(DD) Used to set access options for the locked region. The VDHLM _READ and VDHLM_WRITE flags are for verification purposes and are not mixed with the VDHLM_RESIDENT flag. Either the VDHLM_READ, VDHLM_WRITE, or VDHLM_ RESIDENT flag must be used. Note that VDHLM_RESIDENT cannot be combined with other flags.
 
Possible values are:
 
VDHLM_RESIDENT Lock physical pages.
 
VDHLM_READ Verify read access. VDHLM_READ is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.
 
VDHLM_WRITE Verify write access. VDHLM_WRITE is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.
 
VDHLM_CONTIGUOUS Force physical pages contiguous; can be used only for 64KB or less.
 
VDHLM_NOBLOCK Lock must not give up the CPU.
 
VDHLM_16M Must reside below the 16MB physical memory address.
 
 
 
 
 
=== VDHLockMem Parameter - PagelistArrayPtr ===
 
'''PagelistArrayPtr'''(DD) Pointer to array of VDHPageList_s structures.
 
''VDHLockMem''fills this array. Each ''VDHPageList_s''structure describes a single physically contiguous sub-area of the physical memory that was locked. If ''PagelistArrayPtr''is set to VDHLM_NO_ADDR, no array is returned. The area that ''PagelistArrayPtr''points to must contain enough ''VDHPageList_s''structures to handle a worst case of one structure per page plus one more structure, that is, the region does not begin on a page boundary.
 
 
 
 
 
=== VDHLockMem Parameter - ArrayCountPtr ===
 
'''ArrayCountPtr'''(DD) Pointer to a variable where a count of the number of elements returned in the ''PagelistArrayPtr''array is placed by ''VDHLockMem''. If ''PagelistArrayPtr''is set to VDHLM_NO_ADDR, ''ArrayCountPtr''is ignored.
 
 
 
 
 
=== VDHLockMem Return Value - rc ===
 
Success If the function is successful, it returns a lock handle. This is a global handle that can be used in any task context.
 
Failure If the function fails, it returns 0. If the function fails, call ''VDHGetError''to determine the nature of the problem. If ''NumBytes''equals 0, a system halt occurs.
 
 
 
 
 
=== VDHLockMem - Parameters ===
 
'''StartingLinAddr'''(DD) Starting linear address of the region in the user process that is to be locked.
 
'''NumBytes'''(DD) Size in bytes of the region to lock.
 
'''OptionFlag'''(DD) Used to set access options for the locked region. The VDHLM _READ and VDHLM_WRITE flags are for verification purposes and are not mixed with the VDHLM_RESIDENT flag. Either the VDHLM_READ, VDHLM_WRITE, or VDHLM_ RESIDENT flag must be used. Note that VDHLM_RESIDENT cannot be combined with other flags.
 
Possible values are:
 
VDHLM_RESIDENT Lock physical pages.
 
VDHLM_READ Verify read access. VDHLM_READ is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.
 
VDHLM_WRITE Verify write access. VDHLM_WRITE is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.
 
VDHLM_CONTIGUOUS Force physical pages contiguous; can be used only for 64KB or less.
 
VDHLM_NOBLOCK Lock must not give up the CPU.
 
VDHLM_16M Must reside below the 16MB physical memory address.
 
'''PagelistArrayPtr'''(DD) Pointer to array of VDHPageList_s structures.
 
''VDHLockMem''fills this array. Each ''VDHPageList_s''structure describes a single physically contiguous sub-area of the physical memory that was locked. If ''PagelistArrayPtr''is set to VDHLM_NO_ADDR, no array is returned. The area that ''PagelistArrayPtr''points to must contain enough ''VDHPageList_s''structures to handle a worst case of one structure per page plus one more structure, that is, the region does not begin on a page boundary.
 
'''ArrayCountPtr'''(DD) Pointer to a variable where a count of the number of elements returned in the ''PagelistArrayPtr''array is placed by ''VDHLockMem''. If ''PagelistArrayPtr''is set to VDHLM_NO_ADDR, ''ArrayCountPtr''is ignored.
 
 
 
 
 
=== VDHLockMem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function. There cannot be any memory locked on behalf of a particular DOS session.
 
Notes: The caller must call ''VDHUnlockMem''to remove this lock. All locks are long-term. This function must be used prior to using any pointers passed to a virtual device driver from an OS/2 process (through ''DOSRequestVDD''). This might also be useful to the callers of ''VDHCopyMem''and ''VDHExchangeMem''.
 
''VDHMapPages'', ''VDHReallocPages'', and ''VDHFreePages''will block if applied to pages that are locked. They unblock when the lock is released.
 
 
 
 
 
=== VDHLockMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHMapPages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  maps  a  linear  address  region  in  the  V86  address  space .
* /
 
include  mvdm . inc
 
EXTERN    VDHMapPages : NEAR
pvdhmsSourceRegion    DD  ?      ;    Pointer  to  source  region  definition
pvdhmtTargetRegion    DD  ?      ;    Target  region  definition
flMappingFlag        DD  ?      ;    Mapping  options  flag
 
PUSH      pvdhmsSourceRegion    ;    Push  pvdhmsSourceRegion
PUSH      pvdhmtTargetRegion    ;    Push  pvdhmtTargetRegion
PUSH      flMappingFlag        ;    Push  flMappingFlag
 
CALL      VDHMapPages              ;  Call  the  function </pre>
 
 
 
 
=== VDHMapPages - Format ===
 
 
 
<pre class="western">/*
 
This  function  maps  a  linear  address  region  in  the  V86  address  space .
* /
 
include  mvdm . inc
 
EXTERN    VDHMapPages : NEAR
pvdhmsSourceRegion    DD  ?      ;    Pointer  to  source  region  definition
pvdhmtTargetRegion    DD  ?      ;    Target  region  definition
flMappingFlag        DD  ?      ;    Mapping  options  flag
 
PUSH      pvdhmsSourceRegion    ;    Push  pvdhmsSourceRegion
PUSH      pvdhmtTargetRegion    ;    Push  pvdhmtTargetRegion
PUSH      flMappingFlag        ;    Push  flMappingFlag
 
CALL      VDHMapPages              ;  Call  the  function </pre>
 
 
 
 
=== VDHMapPages Parameter - pvdhmsSourceRegion ===
 
'''pvdhmsSourceRegion'''(DD) Pointer to VDHMAPSOURCE structure.
 
VDHMAPSOURCE is the source region definition for ''VDHMapPages''with a data structure as follows:
 
<pre class="western">VDHMapSource_s STRUC
    vdhms_laddr  DD  ?  ; Source linear address of source memory object.
                          ; Source address to be mapped.  Defines the
                          ; start of the source region for the mapping.
                          ; The region is the same length as the target
                          ; region.
    vdhms_hobj    DD  ?  ; Memory object handle set by the service to
                          ; hold a source handle for VDHMT_LINEAR
                          ; mappings. See the VDHMT_LINEAR description
                          ; under MappingFlag.
VDHMapSource_s ENDS</pre>
 
 
 
 
 
 
=== VDHMapPages Parameter - pvdhmtTargetRegion ===
 
'''pvdhmtTargetRegion'''(DD) Target region definition. Pointer to VDHMAPTARGET structure.
 
VDHMAPTARGET is the target region definition for ''VDHMapPages''with a data structure as follows:
 
<pre class="western">VDHMapTarget_s STRUC
    vdhmt_laddr  DD  ? ; Address in V86-space to be mapped
                          ; (0 &lt;= vdhmt_laddr &lt; 1MB+64KB)
    vdhmt_cpg    DD  ? ; Count of pages to map
    vdhmt_hmap    DD  ? ; Mapping handle.  Must be zero on the first call to
                          ; VDHMapPages for region.  Set by the service to
                          ; hold a handle used for remapping the region. The
                          ; handle is reset each time it is used.  vdhmt_hmap
                          ; must be the value returned from the previous
                          ; VDHMapPages call for the region unless the pages
                          ; are either already invalid or else are being made
                          ; invalid.  If either the old or new mapping is
                          ; invalid pages, vdhmt_hmap can be 0. Making a
                          ; region invalid restores pages in the region to
                          ; their reserved state, and sets vdhmt_hmap to 0.
VDHMapTarget_s ENDS</pre>
 
 
 
 
 
 
=== VDHMapPages Parameter - flMappingFlag ===
 
'''flMappingFlag'''(DD) Mapping options flag.
 
Possible values are:
 
VDHMT_INVALID Make target region pages invalid. ''vdhmt_hmap''can be 0 (zero). This service is faster when the handle is provided, but virtual device drivers that do not store handles can map to invalid before remapping a region. Note that ''pvdhmsSourceRegion''is ignored.
 
VDHMT_LINEAR Map linear source region into target region. ''vdhms_laddr''contains the linear address to map at the start of the target region. This can only be a page-granular address in a memory allocation that was obtained by using ''VDHAllocPages''or ''VDHReallocPages''. After a successful mapping, the target region aliases the corresponding region of the source.
 
''vdhms_hobj''must be 0 (zero) the first time a newly allocated or reallocated source object is mapped. On a successful mapping, ''vdhms_hobj''is filled in. Using this handle on the next mapping that uses the same source object speeds up that mapping call. Any linear address (''laddr'') at the start of the target region can be mapped using the handle. The returned result must be stored after each mapping call. Virtual device drivers can avoid storing this handle and always use 0 (zero), however, the call will be slower.
 
VDHMT_PHYSICAL Map physical source region into target region. ''vdhms_laddr''contains the physical address to map at the start of the target region. ''vdhms_hobj''is ignored.
 
VDHMT_BLACK_HOLE Map target region to black hole pages. ''pvdhmsSourceRegion''is ignored.
 
 
 
 
 
=== VDHMapPages Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHMapPages - Parameters ===
 
'''pvdhmsSourceRegion'''(DD) Pointer to VDHMAPSOURCE structure.
 
VDHMAPSOURCE is the source region definition for ''VDHMapPages''with a data structure as follows:
 
<pre class="western">VDHMapSource_s STRUC
    vdhms_laddr  DD  ?  ; Source linear address of source memory object.
                          ; Source address to be mapped.  Defines the
                          ; start of the source region for the mapping.
                          ; The region is the same length as the target
                          ; region.
    vdhms_hobj    DD  ?  ; Memory object handle set by the service to
                          ; hold a source handle for VDHMT_LINEAR
                          ; mappings. See the VDHMT_LINEAR description
                          ; under MappingFlag.
VDHMapSource_s ENDS</pre>
 
 
'''pvdhmtTargetRegion'''(DD) Target region definition. Pointer to VDHMAPTARGET structure.
 
VDHMAPTARGET is the target region definition for ''VDHMapPages''with a data structure as follows:
 
<pre class="western">VDHMapTarget_s STRUC
    vdhmt_laddr  DD  ? ; Address in V86-space to be mapped
                          ; (0 &lt;= vdhmt_laddr &lt; 1MB+64KB)
    vdhmt_cpg    DD  ? ; Count of pages to map
    vdhmt_hmap    DD  ? ; Mapping handle.  Must be zero on the first call to
                          ; VDHMapPages for region.  Set by the service to
                          ; hold a handle used for remapping the region. The
                          ; handle is reset each time it is used.  vdhmt_hmap
                          ; must be the value returned from the previous
                          ; VDHMapPages call for the region unless the pages
                          ; are either already invalid or else are being made
                          ; invalid.  If either the old or new mapping is
                          ; invalid pages, vdhmt_hmap can be 0. Making a
                          ; region invalid restores pages in the region to
                          ; their reserved state, and sets vdhmt_hmap to 0.
VDHMapTarget_s ENDS</pre>
 
 
'''flMappingFlag'''(DD) Mapping options flag.
 
Possible values are:
 
VDHMT_INVALID Make target region pages invalid. ''vdhmt_hmap''can be 0 (zero). This service is faster when the handle is provided, but virtual device drivers that do not store handles can map to invalid before remapping a region. Note that ''pvdhmsSourceRegion''is ignored.
 
VDHMT_LINEAR Map linear source region into target region. ''vdhms_laddr''contains the linear address to map at the start of the target region. This can only be a page-granular address in a memory allocation that was obtained by using ''VDHAllocPages''or ''VDHReallocPages''. After a successful mapping, the target region aliases the corresponding region of the source.
 
''vdhms_hobj''must be 0 (zero) the first time a newly allocated or reallocated source object is mapped. On a successful mapping, ''vdhms_hobj''is filled in. Using this handle on the next mapping that uses the same source object speeds up that mapping call. Any linear address (''laddr'') at the start of the target region can be mapped using the handle. The returned result must be stored after each mapping call. Virtual device drivers can avoid storing this handle and always use 0 (zero), however, the call will be slower.
 
VDHMT_PHYSICAL Map physical source region into target region. ''vdhms_laddr''contains the physical address to map at the start of the target region. ''vdhms_hobj''is ignored.
 
VDHMT_BLACK_HOLE Map target region to black hole pages. ''pvdhmsSourceRegion''is ignored.
 
 
 
 
 
=== VDHMapPages - Purpose ===
 
This function maps a linear address region in the V86 address space to:
 
*Part of a virtual memory object <br />*Specific physical addresses (for physical devices) <br />*Undefined memory (black holes) <br />*Invalid pages (the unmapped state, which is the default state for reserved pages)
 
''VDHMapPages''also changes the virtual address contents of regions in the V86 address space (below 11000H (1MB+64KB)). Pages in this range can be made to address:
 
*Part of a memory object previously allocated using ''VDHAllocPages''or ''VDHReallocPages''<br />*Physical addresses for a device <br />*Black hole (undefined memory) addresses that are read or written but do not retain their values <br />*Invalid pages, which cause faults when accessed (see ''VDHInstallFaultHook'')
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Mapping succeeds only if it completely replaces a previous mapping, or if the region contains only invalid pages. To change the size of a region, it must first be made invalid. The entire target region must lie below 11000H (1MB+64KB) and must be contained in pages previously reserved by ''VDHReservePages''. ''VDHMapPages''and ''VDHAllocPages''can be used on the same target region but care must be taken. Before switching from one service to the other, the pages affected must first be made invalid. If pages are left invalid, a pagefault handler must be registered (through ''VDHInstallFaultHook'') to handle page faults, in case the pages are accessed.
 
Both target and source addresses must be on page boundaries. If they are not, the page offset part of the address is ignored.
 
 
 
 
 
=== VDHMapPages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHOpen ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  opens  a  file  or  device  and  returns  a  handle .
The  handle  can  be  used  with
VDHRead ,  VDHWrite ,
VDHSeek ,  VDHClose , and
VDHDevIOCtl .
The  parameters  and  error  return  codes  are  the  same  as
those  found  in  the  DosOpen  API .
Refer  to  the
OS / 2  Control  Program  Programming  Reference
for  a  complete  descriptions  of  each  DosOpen  API  parameter .
* /
 
include  mvdm . inc
 
EXTERN    VDHOpen : NEAR
FileName        DD  ?      ;    Pointer  to  the  name  of  the  file  or  device  to  open
FileHandle      DD  ?      ;    Where  the  system  returns  the  file  handle
ActionTaken      DD  ?      ;    Where  a  description  of  the  action  taken  is  returned
FileSize        DD  ?      ;    The  new  file ' s  logical  size  ( EOD )  in  bytes
FileAttribute    DD  ?      ;    File  attribute  bits  used  on  file  creation
OpenFLag        DD  ?      ;    Specifies  action  taken ,  based  on  whether  file  exists
OpenMode        DD  ?      ;    Describes  the  mode  of  the  Open  function
EABuf            DD  ?      ;    Address  of  a  VDH _ EAOP  structure  or  NULL
 
PUSH      FileName        ;    Push  FileName
PUSH      FileHandle      ;    Push  FileHandle
PUSH      ActionTaken      ;    Push  ActionTaken
PUSH      FileSize        ;    Push  FileSize
PUSH      FileAttribute    ;    Push  FileAttribute
PUSH      OpenFLag        ;    Push  OpenFLag
PUSH      OpenMode        ;    Push  OpenMode
PUSH      EABuf            ;    Push  EABuf
 
CALL      VDHOpen        ;  Call  the  function </pre>
 
 
 
 
=== VDHOpen - Format ===
 
 
 
<pre class="western">/*
 
This  function  opens  a  file  or  device  and  returns  a  handle .
The  handle  can  be  used  with
VDHRead ,  VDHWrite ,
VDHSeek ,  VDHClose , and
VDHDevIOCtl .
The  parameters  and  error  return  codes  are  the  same  as
those  found  in  the  DosOpen  API .
Refer  to  the
OS / 2  Control  Program  Programming  Reference
for  a  complete  descriptions  of  each  DosOpen  API  parameter .
* /
 
include  mvdm . inc
 
EXTERN    VDHOpen : NEAR
FileName        DD  ?      ;    Pointer  to  the  name  of  the  file  or  device  to  open
FileHandle      DD  ?      ;    Where  the  system  returns  the  file  handle
ActionTaken      DD  ?      ;    Where  a  description  of  the  action  taken  is  returned
FileSize        DD  ?      ;    The  new  file ' s  logical  size  ( EOD )  in  bytes
FileAttribute    DD  ?      ;    File  attribute  bits  used  on  file  creation
OpenFLag        DD  ?      ;    Specifies  action  taken ,  based  on  whether  file  exists
OpenMode        DD  ?      ;    Describes  the  mode  of  the  Open  function
EABuf            DD  ?      ;    Address  of  a  VDH _ EAOP  structure  or  NULL
 
PUSH      FileName        ;    Push  FileName
PUSH      FileHandle      ;    Push  FileHandle
PUSH      ActionTaken      ;    Push  ActionTaken
PUSH      FileSize        ;    Push  FileSize
PUSH      FileAttribute    ;    Push  FileAttribute
PUSH      OpenFLag        ;    Push  OpenFLag
PUSH      OpenMode        ;    Push  OpenMode
PUSH      EABuf            ;    Push  EABuf
 
CALL      VDHOpen        ;  Call  the  function </pre>
 
 
 
 
=== VDHOpen Parameter - FileName ===
 
'''FileName'''(DD) Pointer to the ASCIIZ string containing the name of the device or file to open.
 
 
 
 
 
=== VDHOpen Parameter - FileHandle ===
 
'''FileHandle'''(DD) Where the system returns the file handle.
 
 
 
 
 
=== VDHOpen Parameter - ActionTaken ===
 
'''ActionTaken'''(DD) Where the system returns a description of the action taken as a result of this function call.
 
 
 
 
 
=== VDHOpen Parameter - FileSize ===
 
'''FileSize'''(DD) The new file's logical size (EOD) in bytes.
 
 
 
 
 
=== VDHOpen Parameter - FileAttribute ===
 
'''FileAttribute'''(DD) File attribute bits used on file creation.
 
 
 
 
 
=== VDHOpen Parameter - OpenFLag ===
 
'''OpenFLag'''(DD) Specifies the action taken depending on whether the file exists.
 
Possible actions are:
 
VDHOPEN_FILE_EXISTED File existed <br />VDHOPEN_FILE_CREATED File created <br />VDHOPEN_FILE_TRUNCATED File replaced
 
 
 
 
 
=== VDHOpen Parameter - OpenMode ===
 
'''OpenMode'''(DD) Describes the mode of the ''Open''function.
 
 
 
 
 
=== VDHOpen Parameter - EABuf ===
 
'''EABuf'''(DD) Address of a VDH_EAOP structure, or NULL.
 
 
 
 
 
=== VDHOpen Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). If the function fails, ''VDHGetError''should be called to determine the nature of the problem. ''VDHGetError''can return the following errors:
 
ERROR_DISK_FULL <br />ERROR_OPEN_FAILED <br />ERROR_FILE_NOT_FOUND <br />ERROR_INVALID_PARAMETER <br />ERROR_PATH_NOT_FOUND <br />ERROR_ACCESS_DENIED <br />ERROR_DRIVE_LOCKED <br />ERROR_NOT_DOS_DISK <br />ERROR_SHARING_BUFFER_EXCEEDED <br />ERROR_SHARING_VIOLATION <br />ERROR_INVALID_ACCESS <br />ERROR_CANNOT_MAKE <br />ERROR_TOO_MANY_OPEN_FILES <br />ERROR_NOT_ENOUGH_MEMORY
 
If the function is called at other than DOS session-task time, or if the ''pszFileName''pointer is invalid, a system halt occurs.
 
 
 
 
 
=== VDHOpen - Parameters ===
 
'''FileName'''(DD) Pointer to the ASCIIZ string containing the name of the device or file to open.
 
'''FileHandle'''(DD) Where the system returns the file handle.
 
'''ActionTaken'''(DD) Where the system returns a description of the action taken as a result of this function call.
 
'''FileSize'''(DD) The new file's logical size (EOD) in bytes.
 
'''FileAttribute'''(DD) File attribute bits used on file creation.
 
'''OpenFLag'''(DD) Specifies the action taken depending on whether the file exists.
 
Possible actions are:
 
VDHOPEN_FILE_EXISTED File existed <br />VDHOPEN_FILE_CREATED File created <br />VDHOPEN_FILE_TRUNCATED File replaced
 
'''OpenMode'''(DD) Describes the mode of the ''Open''function.
 
'''EABuf'''(DD) Address of a VDH_EAOP structure, or NULL.
 
 
 
 
 
=== VDHOpen - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: Any handles the virtual device driver opened for the terminating DOS session must be closed with ''VDHClose''.
 
Notes: Using ''VDHOpen''does not interfere with the handle space available to the DOS session with INT 21H, except that it does count against the system- wide limit on the number of open file handles. These ''VDHOpen''handles and the handles returned from INT 21H $Open cannot be used interchangeably.
 
 
 
 
 
=== VDHOpen - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHOpenPDD ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  gets  the  address  of  the  routine  in  a  physical  device  driver
that  the  virtual  device  driver  uses  to  communicate  with  the  physical  device  driver .
The  physical  device  driver ' s  device  must  have
previously  registered  its  name  and  entry  point  using  the  DevHlp  service
RegisterPDD .
* /
 
include  mvdm . inc
 
EXTERN    VDHOpenPDD : NEAR
DeviceName      DD  ?      ;    Pointer  to  device  name  of  physical  device  driver  to  open
VDDEntryPoint    DQ  ?      ;    VDD  entry  point  for  VDD / PDD  communication
 
PUSH      DeviceName      ;    Push  DeviceName
PUSH      VDDEntryPoint    ;    Push  VDDEntryPoint
 
CALL      VDHOpenPDD        ;  Call  the  function </pre>
 
 
 
 
=== VDHOpenPDD - Format ===
 
 
 
<pre class="western">/*
 
This  function  gets  the  address  of  the  routine  in  a  physical  device  driver
that  the  virtual  device  driver  uses  to  communicate  with  the  physical  device  driver .
The  physical  device  driver ' s  device  must  have
previously  registered  its  name  and  entry  point  using  the  DevHlp  service
RegisterPDD .
* /
 
include  mvdm . inc
 
EXTERN    VDHOpenPDD : NEAR
DeviceName      DD  ?      ;    Pointer  to  device  name  of  physical  device  driver  to  open
VDDEntryPoint    DQ  ?      ;    VDD  entry  point  for  VDD / PDD  communication
 
PUSH      DeviceName      ;    Push  DeviceName
PUSH      VDDEntryPoint    ;    Push  VDDEntryPoint
 
CALL      VDHOpenPDD        ;  Call  the  function </pre>
 
 
 
 
=== VDHOpenPDD Parameter - DeviceName ===
 
'''DeviceName'''(DD) Pointer to the device name of the physical device driver to open.
 
 
 
 
 
=== VDHOpenPDD Parameter - VDDEntryPoint ===
 
'''VDDEntryPoint'''(DQ) Virtual device driver entry point for use by the physical device driver. Since physical device drivers are 16:16 modules, this is a 16:32 entry point.
 
The interface for the ''VDDEntryPoint'':
 
<pre class="western">EntryPoint  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 12] - ulFunc (DD) - Function code
;                        All function codes are private to a PDD/VDD pair.
;          [ESP +  8] - ul1 (DD)    - Function-specific
;                    If a pointer, it is 16:16, and will generally
;                        be an input packet.
;          [ESP +  4] - ul2 (DD)    - Function-specific
;                  If a pointer, it is 16:16, and will generally
;                        be an output packet.
;    EXIT  SUCCESS  Returns a non-zero value in EAX
;          FAILURE  Returns 0 in EAX</pre>
 
 
 
 
 
 
=== VDHOpenPDD Return Value - rc ===
 
Success If the function is successful, it returns a pointer to the physical device driver Inter-Device-Driver Communication (IDC) function. See &quot; RegisterPDD&quot; in the ''OS/2 Physical Device Driver Reference''for a description of the physical device driver's IDC function.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHOpenPDD - Parameters ===
 
'''DeviceName'''(DD) Pointer to the device name of the physical device driver to open.
 
'''VDDEntryPoint'''(DQ) Virtual device driver entry point for use by the physical device driver. Since physical device drivers are 16:16 modules, this is a 16:32 entry point.
 
The interface for the ''VDDEntryPoint'':
 
<pre class="western">EntryPoint  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 12] - ulFunc (DD) - Function code
;                        All function codes are private to a PDD/VDD pair.
;          [ESP +  8] - ul1 (DD)    - Function-specific
;                    If a pointer, it is 16:16, and will generally
;                        be an input packet.
;          [ESP +  4] - ul2 (DD)    - Function-specific
;                  If a pointer, it is 16:16, and will generally
;                        be an output packet.
;    EXIT  SUCCESS  Returns a non-zero value in EAX
;          FAILURE  Returns 0 in EAX</pre>
 
 
 
 
 
 
=== VDHOpenPDD - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Session Terminations: The virtual device driver must communicate with the physical device driver to ensure that any resources the physical device driver has for the terminating DOS session are freed.
 
 
 
 
 
=== VDHOpenPDD - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHOpenVDD ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  a  handle  to  a  virtual  device  driver  that  can
be  used  with  VDHRequestVDD  to  enable  a  virtual  device  driver  to
communicate  with  another  virtual  device  driver .
The  name  must  be  one
that  was  previously  registered  by  using  VDHRegisterVDD .
* /
 
include  mvdm . inc
 
EXTERN    VDHOpenVDD : NEAR
VDDName    DD  ?      ;    Pointer  to  the  name  of  the  virtual  device  driver  to  open
 
PUSH      VDDName    ;    Push  VDDName
 
CALL      VDHOpenVDD ;  Call  the  function </pre>
 
 
 
 
=== VDHOpenVDD - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  a  handle  to  a  virtual  device  driver  that  can
be  used  with  VDHRequestVDD  to  enable  a  virtual  device  driver  to
communicate  with  another  virtual  device  driver .
The  name  must  be  one
that  was  previously  registered  by  using  VDHRegisterVDD .
* /
 
include  mvdm . inc
 
EXTERN    VDHOpenVDD : NEAR
VDDName    DD  ?      ;    Pointer  to  the  name  of  the  virtual  device  driver  to  open
 
PUSH      VDDName    ;    Push  VDDName
 
CALL      VDHOpenVDD ;  Call  the  function </pre>
 
 
 
 
=== VDHOpenVDD Parameter - VDDName ===
 
'''VDDName'''(DD) Pointer to a string containing the name of the virtual device driver to open.
 
 
 
 
 
=== VDHOpenVDD Return Value - rc ===
 
Success If the function is successful, it returns a handle to the virtual device driver.
 
Failure If the function fails, it returns 0 (zero). This can occur if:
 
*The virtual device driver referenced by ''VDDName''is not found. <br />*The virtual device driver was found, but has not registered a worker function (the routine that gets control when this interface is called) for virtual device driver/virtual device driver communication.
 
If this function is called with invalid parameters or in the incorrect context, a system halt occurs.
 
 
 
 
 
=== VDHOpenVDD - Parameters ===
 
'''VDDName'''(DD) Pointer to a string containing the name of the virtual device driver to open.
 
 
 
 
 
=== VDHOpenVDD - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context, typically during DOS session creation.
 
DOS Session Terminations: The virtual device driver must communicate with the opened virtual device driver to ensure that any resources for the terminating DOS session are freed. In addition, the virtual device driver must communicate with any virtual device driver or OS/2 clients to ensure that any resources created due to the connection are freed. Notes: The recommended way for two virtual device drivers to rendezvous with this function is for each to attempt to open the other at the first creation of a DOS session. This allows the two virtual device drivers to work together regardless of the order in which they are initialized.
 
 
 
 
 
=== VDHOpenVDD - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHOpenVIRQ ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  an  IRQ  handle  for  use  with  the  other  Virtual
Programmable  Interrupt  Controller  ( VPIC )  services  and ,  optionally ,  sets
handlers  called  when  an  End  Of  Interrupt  ( EOI )  or  Interrupt  Return
( IRET )  is  executed  during  a  simulated  interrupt .
* /
 
include  mvdm . inc
 
EXTERN    VDHOpenVIRQ : NEAR
IRQNumber      DD  ?      ;    Number  of  the  IRQ  to  open
EOIHandler    DD  ?      ;    Address  of  End - Of - Interrupt  ( EOI )  handler
IRETHandler    DD  ?      ;    Address  of  Interrupt  Return  ( IRET )  handler
Timeout        DD  ?      ;    IRET  timeout  value  in  milliseconds
OptionFlag    DD  ?      ;    Indicates  whether  the  IRQ  can  be  shared
 
PUSH      IRQNumber      ;    Push  IRQNumber
PUSH      EOIHandler    ;    Push  EOIHandler
PUSH      IRETHandler    ;    Push  IRETHandler
PUSH      Timeout        ;    Push  Timeout
PUSH      OptionFlag    ;    Push  OptionFlag
 
CALL      VDHOpenVIRQ      ;  Call  the  function </pre>
 
 
 
 
=== VDHOpenVIRQ - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  an  IRQ  handle  for  use  with  the  other  Virtual
Programmable  Interrupt  Controller  ( VPIC )  services  and ,  optionally ,  sets
handlers  called  when  an  End  Of  Interrupt  ( EOI )  or  Interrupt  Return
( IRET )  is  executed  during  a  simulated  interrupt .
* /
 
include  mvdm . inc
 
EXTERN    VDHOpenVIRQ : NEAR
IRQNumber      DD  ?      ;    Number  of  the  IRQ  to  open
EOIHandler    DD  ?      ;    Address  of  End - Of - Interrupt  ( EOI )  handler
IRETHandler    DD  ?      ;    Address  of  Interrupt  Return  ( IRET )  handler
Timeout        DD  ?      ;    IRET  timeout  value  in  milliseconds
OptionFlag    DD  ?      ;    Indicates  whether  the  IRQ  can  be  shared
 
PUSH      IRQNumber      ;    Push  IRQNumber
PUSH      EOIHandler    ;    Push  EOIHandler
PUSH      IRETHandler    ;    Push  IRETHandler
PUSH      Timeout        ;    Push  Timeout
PUSH      OptionFlag    ;    Push  OptionFlag
 
CALL      VDHOpenVIRQ      ;  Call  the  function </pre>
 
 
 
 
=== VDHOpenVIRQ Parameter - IRQNumber ===
 
'''IRQNumber'''(DD) Number of the IRQ to open.
 
 
 
 
 
=== VDHOpenVIRQ Parameter - EOIHandler ===
 
'''EOIHandler'''(DD) Address of End-Of-Interrupt (EOI) handler.
 
Linear address of the handler to be called when EOI is received by VPIC from a DOS session for the IRQ. If this is not desired, put a 0 (zero) in this parameter. Note that the IRQ is no longer &quot;in service&quot; (the ISR bit has been cleared) when the virtual device driver's EOI handler is called. The interface to the EOI handler is:
 
<pre class="western">EOIHdlr  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT  None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHOpenVIRQ Parameter - IRETHandler ===
 
'''IRETHandler'''(DD) Address of Interrupt Return (IRET) handler.
 
Linear address of the handler to be called when the IRET in the DOS session 's interrupt code is executed for this IRQ. If this is not desired, set the parameter to 0 (zero). The interface for the IRET routine is:
 
<pre class="western">IRETHdlr  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT  None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  DOS session-task</pre>
 
 
 
 
 
 
=== VDHOpenVIRQ Parameter - Timeout ===
 
'''Timeout'''(DD) IRET timeout value in milliseconds. When the timeout expires, the virtual device driver's IRET handler is called as if the IRET had occurred. A value of -1 indicates that no timeout occurs.
 
 
 
 
 
=== VDHOpenVIRQ Parameter - OptionFlag ===
 
'''OptionFlag'''(DD) Option flag. Indicates whether the IRQ can be shared.
 
Possible value:
 
VPIC_SHARE_IRQ Indicates that the virtual device driver is willing to share the IRQ with another virtual device driver. All virtual device drivers that virtualize the same IRQ must pass this flag. Whether a particular IRQ is shared or unshared is determined by the setting of ''OptionFlag''by the first virtual device driver to open the IRQ.
 
 
 
 
 
=== VDHOpenVIRQ Return Value - rc ===
 
Success If the function is successful, it returns an IRQ handle.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''IRQNumber'', ''EOIHandler'', ''IRETHandler'', or ''OptionFlag''are invalid, a system halt occurs.
 
 
 
 
 
=== VDHOpenVIRQ - Parameters ===
 
'''IRQNumber'''(DD) Number of the IRQ to open.
 
'''EOIHandler'''(DD) Address of End-Of-Interrupt (EOI) handler.
 
Linear address of the handler to be called when EOI is received by VPIC from a DOS session for the IRQ. If this is not desired, put a 0 (zero) in this parameter. Note that the IRQ is no longer &quot;in service&quot; (the ISR bit has been cleared) when the virtual device driver's EOI handler is called. The interface to the EOI handler is:
 
<pre class="western">EOIHdlr  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT  None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  DOS session-task</pre>
 
 
'''IRETHandler'''(DD) Address of Interrupt Return (IRET) handler.
 
Linear address of the handler to be called when the IRET in the DOS session 's interrupt code is executed for this IRQ. If this is not desired, set the parameter to 0 (zero). The interface for the IRET routine is:
 
<pre class="western">IRETHdlr  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT  None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT  DOS session-task</pre>
 
 
'''Timeout'''(DD) IRET timeout value in milliseconds. When the timeout expires, the virtual device driver's IRET handler is called as if the IRET had occurred. A value of -1 indicates that no timeout occurs.
 
'''OptionFlag'''(DD) Option flag. Indicates whether the IRQ can be shared.
 
Possible value:
 
VPIC_SHARE_IRQ Indicates that the virtual device driver is willing to share the IRQ with another virtual device driver. All virtual device drivers that virtualize the same IRQ must pass this flag. Whether a particular IRQ is shared or unshared is determined by the setting of ''OptionFlag''by the first virtual device driver to open the IRQ.
 
 
 
 
 
=== VDHOpenVIRQ - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: A maximum of 32 virtual device drivers can share an IRQ.
 
 
 
 
 
=== VDHOpenVIRQ - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPhysicalDisk ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  information  about  partitionable  disks .
* /
 
include  mvdm . inc
 
EXTERN    VDHPhysicalDisk : NEAR
Function    DD  ?      ;    Type  of  partitionable  disks '  information
DataPtr    DD  ?      ;    Pointer  to  the  return  buffer
DataLen    DD  ?      ;    Length  of  the  return  buffer
ParmPtr    DD  ?      ;    Pointer  to  the  user - supplied  information
ParmLen    DD  ?      ;    Length  of  the  user - supplied  information
 
PUSH      Function    ;    Push  Function
PUSH      DataPtr    ;    Push  DataPtr
PUSH      DataLen    ;    Push  DataLen
PUSH      ParmPtr    ;    Push  ParmPtr
PUSH      ParmLen    ;    Push  ParmLen
 
CALL      VDHPhysicalDisk  ;  Call  the  function </pre>
 
 
 
 
=== VDHPhysicalDisk - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  information  about  partitionable  disks .
* /
 
include  mvdm . inc
 
EXTERN    VDHPhysicalDisk : NEAR
Function    DD  ?      ;    Type  of  partitionable  disks '  information
DataPtr    DD  ?      ;    Pointer  to  the  return  buffer
DataLen    DD  ?      ;    Length  of  the  return  buffer
ParmPtr    DD  ?      ;    Pointer  to  the  user - supplied  information
ParmLen    DD  ?      ;    Length  of  the  user - supplied  information
 
PUSH      Function    ;    Push  Function
PUSH      DataPtr    ;    Push  DataPtr
PUSH      DataLen    ;    Push  DataLen
PUSH      ParmPtr    ;    Push  ParmPtr
PUSH      ParmLen    ;    Push  ParmLen
 
CALL      VDHPhysicalDisk  ;  Call  the  function </pre>
 
 
 
 
=== VDHPhysicalDisk Parameter - Function ===
 
'''Function'''(DD) Type of partitionable disks' information to obtain.
 
Possible values are:
 
VDHPHYD_GET_DISKS Obtain the total number of partitionable disks <br />VDHPHYD_GET_HANDLE Obtain a handle to use with the Category 9 IOCtls <br />VDHPHYD_RELEASE_HANDLE Release a handle for a partitionable disk
 
 
 
 
 
=== VDHPhysicalDisk Parameter - DataPtr ===
 
'''DataPtr'''(DD) Pointer to the return buffer.
 
 
 
 
 
=== VDHPhysicalDisk Parameter - DataLen ===
 
'''DataLen'''(DD) Length of the return buffer.
 
The returned data for each function is described as follows (all lengths are in bytes):
 
VDHPHYD_GET_DISKS Data Length=2. Total number of partitionable disks in the system. 1-based.
 
VDHPHYD_GET_HANDLE Data Length=2. Handle for the specified partitionable disk for Category 9 IOCtls.
 
VDHPHYD_RELEASE_HANDLE Data Length=0. None; pointer must be 0 (zero).
 
 
 
 
 
=== VDHPhysicalDisk Parameter - ParmPtr ===
 
'''ParmPtr'''(DD) Pointer to the user-supplied information.
 
 
 
 
 
=== VDHPhysicalDisk Parameter - ParmLen ===
 
'''ParmLen'''(DD) Length of the user-supplied information (all lengths are in bytes):
 
VDHPHYD_GET_DISKS Parm Length=0. None; must be set to 0 (zero). 1-based.
 
VDHPHYD_GET_HANDLE Parm Length=string length. ASCIIZ string that specifies the partitionable disk.
 
VDHPHYD_RELEASE_HANDLE Parm Length=2. Handle obtained from VDHPHYD_GET_ HANDLE.
 
 
 
 
 
=== VDHPhysicalDisk Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. ''VDHGetError''can return the following error codes:
 
ERROR_ACCESS_DENIED <br />ERROR_INVALID_FUNCTION <br />ERROR_INVALID_HANDLE <br />ERROR_INVALID_PARAMETER <br />ERROR_LOCK_VIOLATION
 
If ''VDHPhysicalDisk''is called in any context except DOS session task time, a system halt occurs.
 
 
 
 
 
=== VDHPhysicalDisk - Parameters ===
 
'''Function'''(DD) Type of partitionable disks' information to obtain.
 
Possible values are:
 
VDHPHYD_GET_DISKS Obtain the total number of partitionable disks <br />VDHPHYD_GET_HANDLE Obtain a handle to use with the Category 9 IOCtls <br />VDHPHYD_RELEASE_HANDLE Release a handle for a partitionable disk
 
'''DataPtr'''(DD) Pointer to the return buffer.
 
'''DataLen'''(DD) Length of the return buffer.
 
The returned data for each function is described as follows (all lengths are in bytes):
 
VDHPHYD_GET_DISKS Data Length=2. Total number of partitionable disks in the system. 1-based.
 
VDHPHYD_GET_HANDLE Data Length=2. Handle for the specified partitionable disk for Category 9 IOCtls.
 
VDHPHYD_RELEASE_HANDLE Data Length=0. None; pointer must be 0 (zero).
 
'''ParmPtr'''(DD) Pointer to the user-supplied information.
 
'''ParmLen'''(DD) Length of the user-supplied information (all lengths are in bytes):
 
VDHPHYD_GET_DISKS Parm Length=0. None; must be set to 0 (zero). 1-based.
 
VDHPHYD_GET_HANDLE Parm Length=string length. ASCIIZ string that specifies the partitionable disk.
 
VDHPHYD_RELEASE_HANDLE Parm Length=2. Handle obtained from VDHPHYD_GET_ HANDLE.
 
 
 
 
 
=== VDHPhysicalDisk - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: The handle obtained with Function Value=2 is released with Function Value=3. The ASCIIZ string used to specify the partitionable disk must be of the following format:
 
<pre class="western">    number:&lt;null byte&gt;
 
    Where:
          number      Specifies the partitionable disk (1-based) number in ASCII
          :            Must be present
          &lt;null byte&gt;  Specifies the byte of 0 for the ASCIIZ string</pre>
Notes: If the pointers passed by this function are allocated from the stack , then the ''SSToDS''macro must be used to make the DS pointer relative. Addresses (pointers) inside device-specific data and parameter packets are not translated.
 
 
 
 
 
=== VDHPhysicalDisk - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPopInt ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  reverses  the  effects  of  VDHPushInt .
It  removes  the  Interrupt  Return
( IRET )  frame  from  the  client ' s  stack  and  restores
the  client ' s  CS : IP
to  what  was  in  the  IRET  frame .
* /
 
include  mvdm . inc
 
EXTERN    VDHPopInt : NEAR
    DD  ?
 
PUSH          ;    Push
 
CALL      VDHP ;  Call  the  function </pre>
 
 
 
 
=== VDHPopInt - Format ===
 
 
 
<pre class="western">/*
 
This  function  reverses  the  effects  of  VDHPushInt .
It  removes  the  Interrupt  Return
( IRET )  frame  from  the  client ' s  stack  and  restores
the  client ' s  CS : IP
to  what  was  in  the  IRET  frame .
* /
 
include  mvdm . inc
 
EXTERN    VDHPopInt : NEAR
    DD  ?
 
PUSH          ;    Push
 
CALL      VDHP ;  Call  the  function </pre>
 
 
 
 
=== VDHPopInt Parameter - ===
 
(DD) None.
 
 
 
 
 
=== VDHPopInt Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack overflow would occur. A stack exception will be simulated to the client.
 
 
 
 
 
=== VDHPopInt - Parameters ===
 
(DD) None.
 
 
 
 
 
=== VDHPopInt - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This function always returns Successful when the DOS session is in client mode because no data accesses below 1MB can cause a fault.
 
 
 
 
 
=== VDHPopInt - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPopRegs ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  reverses  the
VDHPushRegs  by  popping  the
specified  client  registers  into  the  Client  Register  Frame  ( CRF )  from
the  client ' s  stack .
* /
 
include  mvdm . inc
 
EXTERN    VDHPopRegs : NEAR
RegFlag    DD  ?      ;    Indicates  which  client  registers  to  pop
 
PUSH      RegFlag    ;    Push  RegFlag
 
CALL      VDHPopRegs ;  Call  the  function </pre>
 
 
 
 
=== VDHPopRegs - Format ===
 
 
 
<pre class="western">/*
 
This  function  reverses  the
VDHPushRegs  by  popping  the
specified  client  registers  into  the  Client  Register  Frame  ( CRF )  from
the  client ' s  stack .
* /
 
include  mvdm . inc
 
EXTERN    VDHPopRegs : NEAR
RegFlag    DD  ?      ;    Indicates  which  client  registers  to  pop
 
PUSH      RegFlag    ;    Push  RegFlag
 
CALL      VDHPopRegs ;  Call  the  function </pre>
 
 
 
 
=== VDHPopRegs Parameter - RegFlag ===
 
'''RegFlag'''(DD) Flag indicating which client registers to pop.
 
These flags can be &quot;ORed&quot; together to indicate more than one register. Possible values are:
 
VDHREG_AX Pop the AX register <br />VDHREG_BX Pop the BX register <br />VDHREG_CX Pop the CX register <br />VDHREG_DX Pop the DX register <br />VDHREG_SI Pop the SI register <br />VDHREG_DI Pop the DI register <br />VDHREG_BP Pop the BP register <br />VDHREG_SP Pop the SP register <br />VDHREG_DS Pop the DS register <br />VDHREG_ES Pop the ES register <br />VDHREG_SS Pop the SS register <br />VDHREG_FLAG Pop the Flags register <br />VDHREG_ALL Pop all the registers <br />VDHREG_GENERAL Pop all the registers except SS and SP
 
 
 
 
 
=== VDHPopRegs Return Value - rc ===
 
Success If the function was successful, it returns a nonzero value.
 
Failure If this function fails, it returns 0 (zero) if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception is simulated to the client. If ''RegFlag''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHPopRegs - Parameters ===
 
'''RegFlag'''(DD) Flag indicating which client registers to pop.
 
These flags can be &quot;ORed&quot; together to indicate more than one register. Possible values are:
 
VDHREG_AX Pop the AX register <br />VDHREG_BX Pop the BX register <br />VDHREG_CX Pop the CX register <br />VDHREG_DX Pop the DX register <br />VDHREG_SI Pop the SI register <br />VDHREG_DI Pop the DI register <br />VDHREG_BP Pop the BP register <br />VDHREG_SP Pop the SP register <br />VDHREG_DS Pop the DS register <br />VDHREG_ES Pop the ES register <br />VDHREG_SS Pop the SS register <br />VDHREG_FLAG Pop the Flags register <br />VDHREG_ALL Pop all the registers <br />VDHREG_GENERAL Pop all the registers except SS and SP
 
 
 
 
 
=== VDHPopRegs - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: The caller should be careful to pass the same ''RegFlag''value to ''VDHPopRegs''that was used for the corresponding ''VDHPushRegs''call. If the caller does not do this, the client stack can become damaged. This function always returns Successful when ''RegFlag''is valid and the DOS session is in V86 mode because no data accesses below 1MB can cause a fault.
 
 
 
 
 
=== VDHPopRegs - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPopStack ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  pops  the  data  off  the  client ' s  stack .
* /
 
include  mvdm . inc
 
EXTERN    VDHPopStack : NEAR
NumBytes    DD  ?      ;    Number  of  bytes  to  pop  off  the  client ' s  stack
DataPtr    DD  ?      ;    Pointer  to  data  to  pop  off  client ' s  stack
 
PUSH      NumBytes    ;    Push  NumBytes
PUSH      DataPtr    ;    Push  DataPtr
 
CALL      VDHPopStack  ;  Call  the  function </pre>
 
 
 
 
=== VDHPopStack - Format ===
 
 
 
<pre class="western">/*
 
This  function  pops  the  data  off  the  client ' s  stack .
* /
 
include  mvdm . inc
 
EXTERN    VDHPopStack : NEAR
NumBytes    DD  ?      ;    Number  of  bytes  to  pop  off  the  client ' s  stack
DataPtr    DD  ?      ;    Pointer  to  data  to  pop  off  client ' s  stack
 
PUSH      NumBytes    ;    Push  NumBytes
PUSH      DataPtr    ;    Push  DataPtr
 
CALL      VDHPopStack  ;  Call  the  function </pre>
 
 
 
 
=== VDHPopStack Parameter - NumBytes ===
 
'''NumBytes'''(DD) Number of bytes to pop off the client's stack. Must be an even number.
 
 
 
 
 
=== VDHPopStack Parameter - DataPtr ===
 
'''DataPtr'''(DD) Pointer to the data to pop off the client's stack.
 
 
 
 
 
=== VDHPopStack Return Value - rc ===
 
Success If the function was successful, it returns a nonzero value.
 
Failure If this function fails, it returns 0 (zero) if a fault would occur when accessing the user stack. If ''NumBytes''is odd, a system halt occurs.
 
 
 
 
 
=== VDHPopStack - Parameters ===
 
'''NumBytes'''(DD) Number of bytes to pop off the client's stack. Must be an even number.
 
'''DataPtr'''(DD) Pointer to the data to pop off the client's stack.
 
 
 
 
 
=== VDHPopStack - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This is a very low-level service. Appropriate care should be exercised in its use to ensure that the client's stack is not damaged. This service handles stack wraparound, and always returns successful when the DOS session is in V86-mode because no data accesses below 1MB can cause a fault.
 
 
 
 
 
=== VDHPopStack - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPopup ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  displays  a  message  according  to  the  Message  ID ,  and
gets  a  response  from  the  user .
* /
 
include  mvdm . inc
 
EXTERN    VDHPopup : NEAR
ParmTable      DD  ?      ;    Pointer  to  a  table  of  substitution  strings
StrCount      DD  ?      ;    Number  of  substitution  strings
MsgNumber      DD  ?      ;    Message  number
RespPtr        DD  ?      ;    Pointer  to  a  DD  to  receive  the  response
RespAllowed    DD  ?      ;    Bit  field  describing  the  allowed  responses
Reserved      DD  ?      ;    Reserved ;  must  be  set  to  NULL
 
PUSH      ParmTable      ;    Push  ParmTable
PUSH      StrCount      ;    Push  StrCount
PUSH      MsgNumber      ;    Push  MsgNumber
PUSH      RespPtr        ;    Push  RespPtr
PUSH      RespAllowed    ;    Push  RespAllowed
PUSH      Reserved      ;    Push  Reserved
 
CALL      VDHPopup      ;  Call  the  function </pre>
 
 
 
 
=== VDHPopup - Format ===
 
 
 
<pre class="western">/*
 
This  function  displays  a  message  according  to  the  Message  ID ,  and
gets  a  response  from  the  user .
* /
 
include  mvdm . inc
 
EXTERN    VDHPopup : NEAR
ParmTable      DD  ?      ;    Pointer  to  a  table  of  substitution  strings
StrCount      DD  ?      ;    Number  of  substitution  strings
MsgNumber      DD  ?      ;    Message  number
RespPtr        DD  ?      ;    Pointer  to  a  DD  to  receive  the  response
RespAllowed    DD  ?      ;    Bit  field  describing  the  allowed  responses
Reserved      DD  ?      ;    Reserved ;  must  be  set  to  NULL
 
PUSH      ParmTable      ;    Push  ParmTable
PUSH      StrCount      ;    Push  StrCount
PUSH      MsgNumber      ;    Push  MsgNumber
PUSH      RespPtr        ;    Push  RespPtr
PUSH      RespAllowed    ;    Push  RespAllowed
PUSH      Reserved      ;    Push  Reserved
 
CALL      VDHPopup      ;  Call  the  function </pre>
 
 
 
 
=== VDHPopup Parameter - ParmTable ===
 
'''ParmTable'''(DD) Pointer to a table of substitution strings.
 
 
 
 
 
=== VDHPopup Parameter - StrCount ===
 
'''StrCount'''(DD) Number of substitution strings.
 
 
 
 
 
=== VDHPopup Parameter - MsgNumber ===
 
'''MsgNumber'''(DD) Message number.
 
 
 
 
 
=== VDHPopup Parameter - RespPtr ===
 
'''RespPtr'''(DD) Pointer to a DD to receive the returned response, filled on exit.
 
 
 
 
 
=== VDHPopup Parameter - RespAllowed ===
 
'''RespAllowed'''(DD) Bit field describing the allowed responses.
 
The allowed values are (any combination of these flags can be specified):
 
VDHP_FAIL (0001H) <br />VDHP_RETRY (0004H) <br />VDHP_IGNORE (0008H) <br />VDHP_TERMINATE_SESSION (0002H)
 
 
 
 
 
=== VDHPopup Parameter - Reserved ===
 
'''Reserved'''(DD) Reserved. Must be set to NULL.
 
 
 
 
 
=== VDHPopup Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value and the variable pointed to by ''RespPtr''is filled in with actual response selected by the user.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHPopup - Parameters ===
 
'''ParmTable'''(DD) Pointer to a table of substitution strings.
 
'''StrCount'''(DD) Number of substitution strings.
 
'''MsgNumber'''(DD) Message number.
 
'''RespPtr'''(DD) Pointer to a DD to receive the returned response, filled on exit.
 
'''RespAllowed'''(DD) Bit field describing the allowed responses.
 
The allowed values are (any combination of these flags can be specified):
 
VDHP_FAIL (0001H) <br />VDHP_RETRY (0004H) <br />VDHP_IGNORE (0008H) <br />VDHP_TERMINATE_SESSION (0002H)
 
'''Reserved'''(DD) Reserved. Must be set to NULL.
 
 
 
 
 
=== VDHPopup - Purpose ===
 
Context Issues: This function can be called in the initialization context or the DOS session-task context. If it is called at initialization time, the message is displayed as a string on the console as if a ''DosWrite''to standard output (''stdout'') had been made. No prompt is displayed, and no user response is returned. ''ResponsePtr''is filled in with 0 (zero).
 
DOS Session Terminations: A DOS session cannot be terminated if it is waiting in this call for a user response.
 
Notes: This service is intended for virtual device drivers, which must inform the user of some extraordinary circumstance. For example, the virtual COM device driver (VCOM) issues this call to inform the user that a COM port is busy and gives the user a choice of how to handle the situation .
 
The input value of ''ResponsePtr''is not used. &quot;Retry&quot; is the default action chosen for hard errors. If Retry is not allowed, &quot;End the Program&quot; is chosen as the default.
 
 
 
 
 
=== VDHPopup - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPostEventSem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  posts  an  event  semaphore .
All  the  threads  blocked  on  this  semaphore  will  wake  up .
* /
 
include  mvdm . inc
 
EXTERN    VDHPostEventSem : NEAR
EventSemHandle    DD  ?      ;    Handle  of  an  event  semaphore
 
PUSH      EventSemHandle    ;    Push  EventSemHandle
 
CALL      VDHPostEventSem        ;  Call  the  function </pre>
 
 
 
 
=== VDHPostEventSem - Format ===
 
 
 
<pre class="western">/*
 
This  function  posts  an  event  semaphore .
All  the  threads  blocked  on  this  semaphore  will  wake  up .
* /
 
include  mvdm . inc
 
EXTERN    VDHPostEventSem : NEAR
EventSemHandle    DD  ?      ;    Handle  of  an  event  semaphore
 
PUSH      EventSemHandle    ;    Push  EventSemHandle
 
CALL      VDHPostEventSem        ;  Call  the  function </pre>
 
 
 
 
=== VDHPostEventSem Parameter - EventSemHandle ===
 
'''EventSemHandle'''(DD) Handle of the event semaphore to post.
 
 
 
 
 
=== VDHPostEventSem Return Value - rc ===
 
Success If the function is successful, it will return nothing.
 
Failure Posting a semaphore that is invalid or is already posted causes a system halt to occur.
 
 
 
 
 
=== VDHPostEventSem - Parameters ===
 
'''EventSemHandle'''(DD) Handle of the event semaphore to post.
 
 
 
 
 
=== VDHPostEventSem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHPostEventSem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPrintClose ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  called  by  other  virtual  device  drivers  to  flush  and
close  a  DOS  session ' s  open  printers  that  have  been  opened  for  INT  17H
printing .
A  DOS  session  can  have  more  than  one  printer  open .
This  service  flushes  and  closes  all  of  them .
* /
 
include  mvdm . inc
 
EXTERN    VDHPrintClose : NEAR
VDMHandle    DD  ?      ;    DOS  session  handle
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHPrintClose    ;  Call  the  function </pre>
 
 
 
 
=== VDHPrintClose - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  called  by  other  virtual  device  drivers  to  flush  and
close  a  DOS  session ' s  open  printers  that  have  been  opened  for  INT  17H
printing .
A  DOS  session  can  have  more  than  one  printer  open .
This  service  flushes  and  closes  all  of  them .
* /
 
include  mvdm . inc
 
EXTERN    VDHPrintClose : NEAR
VDMHandle    DD  ?      ;    DOS  session  handle
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHPrintClose    ;  Call  the  function </pre>
 
 
 
 
=== VDHPrintClose Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) DOS session handle.
 
 
 
 
 
=== VDHPrintClose Return Value - rc ===
 
None.
 
 
 
 
 
=== VDHPrintClose - Parameters ===
 
'''VDMHandle'''(DD) DOS session handle.
 
 
 
 
 
=== VDHPrintClose - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: The system will flush and close any open printers when the DOS session is terminated.
 
Notes: If a printer has been left open because of direct access to the parallel ports, it will also be closed.
 
 
 
 
 
=== VDHPrintClose - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPushFarCall ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  simulates  a  Far  Call  to  V86  code  as  if  a  DOS  program
had  executed  a  Far  Call  instruction .
* /
 
include  mvdm . inc
 
EXTERN    VDHPushFarCall : NEAR
SegOffAddr    DQ  ?      ;    Address  of  V86  mode  or  protected  mode  code  to  call
 
PUSH      SegOffAddr    ;    Push  SegOffAddr
 
CALL      VDHPushFarCall    ;  Call  the  function </pre>
 
 
 
 
=== VDHPushFarCall - Format ===
 
 
 
<pre class="western">/*
 
This  function  simulates  a  Far  Call  to  V86  code  as  if  a  DOS  program
had  executed  a  Far  Call  instruction .
* /
 
include  mvdm . inc
 
EXTERN    VDHPushFarCall : NEAR
SegOffAddr    DQ  ?      ;    Address  of  V86  mode  or  protected  mode  code  to  call
 
PUSH      SegOffAddr    ;    Push  SegOffAddr
 
CALL      VDHPushFarCall    ;  Call  the  function </pre>
 
 
 
 
=== VDHPushFarCall Parameter - SegOffAddr ===
 
'''SegOffAddr'''(DQ) The V86-mode segment:offset address of the V86-mode code to call, or selector:offset of protected-mode code to call.
 
 
 
 
 
=== VDHPushFarCall Return Value - rc ===
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception is simulated to the client.
 
 
 
 
 
=== VDHPushFarCall - Parameters ===
 
'''SegOffAddr'''(DQ) The V86-mode segment:offset address of the V86-mode code to call, or selector:offset of protected-mode code to call.
 
 
 
 
 
=== VDHPushFarCall - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This function does not take effect until the operating system returns to the DOS session. In most cases, ''VDHArmReturnHook''is called after this service. This allows the virtual device driver to regain control when the called V86 code executes its Far Return (RETF).
 
This function always returns successful when the DOS session is in V86 mode because no data accesses below 1MB can cause a fault.
 
 
 
 
 
=== VDHPushFarCall - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPushInt ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  to  change  the  DOS  session ' s  control  flow  to  the
interrupt  handler  when  an  interrupt  is  simulated .
This  function  also  simulates  an  interrupt
to  a  specified  V86 - interrupt  vector  as  if  a  DOS  program  has  executed
an  INT  n  instruction .
Any  virtual  device  driver  hooked  on  this  interrupt  with  VDHInstallIntHook
will  get  control  as  expected .
The  VDHArmReturnHook  service  can  be  used  after  this
function  is  called  to
regain  control  when  the  V86  code  executes  the  Interrupt  Return  ( IRET ) .
 
If  the  DOS  session  is  in  V86 - mode ,  the  V86 - mode  handler  from  the  IVT  is
called .
If  the  DOS  session  is  in  protected  mode ,  the  protected - mode  interrupt
handler  is  called .
* /
 
include  mvdm . inc
 
EXTERN    VDHPushInt : NEAR
Vector    DD  ?      ;    Number  of  the  interrupt  vector  to  push
 
PUSH      Vector    ;    Push  Vector
 
CALL      VDHPushIn ;  Call  the  function </pre>
 
 
 
 
=== VDHPushInt - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  to  change  the  DOS  session ' s  control  flow  to  the
interrupt  handler  when  an  interrupt  is  simulated .
This  function  also  simulates  an  interrupt
to  a  specified  V86 - interrupt  vector  as  if  a  DOS  program  has  executed
an  INT  n  instruction .
Any  virtual  device  driver  hooked  on  this  interrupt  with  VDHInstallIntHook
will  get  control  as  expected .
The  VDHArmReturnHook  service  can  be  used  after  this
function  is  called  to
regain  control  when  the  V86  code  executes  the  Interrupt  Return  ( IRET ) .
 
If  the  DOS  session  is  in  V86 - mode ,  the  V86 - mode  handler  from  the  IVT  is
called .
If  the  DOS  session  is  in  protected  mode ,  the  protected - mode  interrupt
handler  is  called .
* /
 
include  mvdm . inc
 
EXTERN    VDHPushInt : NEAR
Vector    DD  ?      ;    Number  of  the  interrupt  vector  to  push
 
PUSH      Vector    ;    Push  Vector
 
CALL      VDHPushIn ;  Call  the  function </pre>
 
 
 
 
=== VDHPushInt Parameter - Vector ===
 
'''Vector'''(DD) Number of the interrupt vector to push (0-255).
 
 
 
 
 
=== VDHPushInt Return Value - rc ===
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If ''Vector''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHPushInt - Parameters ===
 
'''Vector'''(DD) Number of the interrupt vector to push (0-255).
 
 
 
 
 
=== VDHPushInt - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This function does not take effect until the operating system returns to V86 mode. This function always returns successful when the DOS session is in V86 mode because no data accesses below 1MB can cause a fault .
 
 
 
 
 
=== VDHPushInt - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPushRegs ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  pushes  the  specified  client  register  from  the  Client
Register  Frame  ( CRF )  to  the  client ' s  stack .
This  service  is  usually
used  in  conjunction  with  VDHPushFarCall  to  preserve  user  registers .
* /
 
include  mvdm . inc
 
EXTERN    VDHPushRegs : NEAR
RegFlag    DD  ?      ;    Flag  indicating  which  client  registers  to  push
 
PUSH      RegFlag    ;    Push  RegFlag
 
CALL      VDHPushRegs ;  Call  the  function </pre>
 
 
 
 
=== VDHPushRegs - Format ===
 
 
 
<pre class="western">/*
 
This  function  pushes  the  specified  client  register  from  the  Client
Register  Frame  ( CRF )  to  the  client ' s  stack .
This  service  is  usually
used  in  conjunction  with  VDHPushFarCall  to  preserve  user  registers .
* /
 
include  mvdm . inc
 
EXTERN    VDHPushRegs : NEAR
RegFlag    DD  ?      ;    Flag  indicating  which  client  registers  to  push
 
PUSH      RegFlag    ;    Push  RegFlag
 
CALL      VDHPushRegs ;  Call  the  function </pre>
 
 
 
 
=== VDHPushRegs Parameter - RegFlag ===
 
'''RegFlag'''(DD) Flag indicating which client registers to push. These flags can be ORed together to indicate more than one register.
 
Possible values are:
 
VDHREG_AX Push the AX register <br />VDHREG_BX Push the BX register <br />VDHREG_CX Push the CX register <br />VDHREG_DX Push the DX register <br />VDHREG_SI Push the SI register <br />VDHREG_DI Push the DI register <br />VDHREG_BP Push the BP register <br />VDHREG_SP Push the SP register <br />VDHREG_DS Push the DS register <br />VDHREG_ES Push the ES register <br />VDHREG_SS Push the SS register <br />VDHREG_FLAG Push the Flags register <br />VDHREG_ALL Push all the registers <br />VDHREG_GENERAL Push all the registers except SS and SP
 
 
 
 
 
=== VDHPushRegs Return Value - rc ===
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If ''RegFlag''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHPushRegs - Parameters ===
 
'''RegFlag'''(DD) Flag indicating which client registers to push. These flags can be ORed together to indicate more than one register.
 
Possible values are:
 
VDHREG_AX Push the AX register <br />VDHREG_BX Push the BX register <br />VDHREG_CX Push the CX register <br />VDHREG_DX Push the DX register <br />VDHREG_SI Push the SI register <br />VDHREG_DI Push the DI register <br />VDHREG_BP Push the BP register <br />VDHREG_SP Push the SP register <br />VDHREG_DS Push the DS register <br />VDHREG_ES Push the ES register <br />VDHREG_SS Push the SS register <br />VDHREG_FLAG Push the Flags register <br />VDHREG_ALL Push all the registers <br />VDHREG_GENERAL Push all the registers except SS and SP
 
 
 
 
 
=== VDHPushRegs - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Because the registers are saved on the DOS session stack (as opposed to a virtual device driver data structure), the virtual device driver is in no danger of losing track of data if the DOS session does not return to the virtual device driver. This service is used sparingly as it consumes DOS session stack space, and most DOS applications cannot tolerate excessive stack usage beyond their own needs.
 
This function always returns successful when ''RegFlag''is valid and the DOS session is in V86 mode because no data accessed below 1MB can cause a fault .
 
 
 
 
 
=== VDHPushRegs - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPushStack ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  pushes  data  onto  the  client ' s  stack .
* /
 
include  mvdm . inc
 
EXTERN    VDHPushStack : NEAR
NumBytes    DD  ?      ;    Number  of  bytes  to  push  on  the  client ' s  stack
DataPtr    DD  ?      ;    Pointer  to  the  data  to  push  on  the  stack
 
PUSH      NumBytes    ;    Push  NumBytes
PUSH      DataPtr    ;    Push  DataPtr
 
CALL      VDHPushStack  ;  Call  the  function </pre>
 
 
 
 
=== VDHPushStack - Format ===
 
 
 
<pre class="western">/*
 
This  function  pushes  data  onto  the  client ' s  stack .
* /
 
include  mvdm . inc
 
EXTERN    VDHPushStack : NEAR
NumBytes    DD  ?      ;    Number  of  bytes  to  push  on  the  client ' s  stack
DataPtr    DD  ?      ;    Pointer  to  the  data  to  push  on  the  stack
 
PUSH      NumBytes    ;    Push  NumBytes
PUSH      DataPtr    ;    Push  DataPtr
 
CALL      VDHPushStack  ;  Call  the  function </pre>
 
 
 
 
=== VDHPushStack Parameter - NumBytes ===
 
'''NumBytes'''(DD) Number of bytes to push onto the client's stack. Must be an even number.
 
 
 
 
 
=== VDHPushStack Parameter - DataPtr ===
 
'''DataPtr'''(DD) A pointer to the data to be pushed.
 
 
 
 
 
=== VDHPushStack Return Value - rc ===
 
Success If the function was successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If NumBytes is odd, a system halt occurs.
 
 
 
 
 
=== VDHPushStack - Parameters ===
 
'''NumBytes'''(DD) Number of bytes to push onto the client's stack. Must be an even number.
 
'''DataPtr'''(DD) A pointer to the data to be pushed.
 
 
 
 
 
=== VDHPushStack - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This is a very low-level service. Appropriate care should be exercised in its use to ensure that the client's stack is not corrupted. This service handles stack wraparound, and always returns successful when the DOS session is in V86-mode because no data accesses below 1MB can cause a fault.
 
 
 
 
 
=== VDHPushStack - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHPutSysValue ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  sets  a  system  value .
* /
 
include  mvdm . inc
 
EXTERN    VDHPutSysValue : NEAR
Index    DD  ?      ;    Index  of  the  system  variable  to  set
Value    DD  ?      ;    New  value  for  the  system  variable
 
PUSH      Index    ;    Push  Index
PUSH      Value    ;    Push  Value
 
CALL      VDHPutSysVal ;  Call  the  function </pre>
 
 
 
 
=== VDHPutSysValue - Format ===
 
 
 
<pre class="western">/*
 
This  function  sets  a  system  value .
* /
 
include  mvdm . inc
 
EXTERN    VDHPutSysValue : NEAR
Index    DD  ?      ;    Index  of  the  system  variable  to  set
Value    DD  ?      ;    New  value  for  the  system  variable
 
PUSH      Index    ;    Push  Index
PUSH      Value    ;    Push  Value
 
CALL      VDHPutSysVal ;  Call  the  function </pre>
 
 
 
 
=== VDHPutSysValue Parameter - Index ===
 
'''Index'''(DD) Index of the system value to set. System value indexes are defined in VDMM.INC and listed in [[00822.htm|VDHQuerySysValue]].
 
 
 
 
 
=== VDHPutSysValue Parameter - Value ===
 
'''Value'''(DD) New value for the system variable.
 
 
 
 
 
=== VDHPutSysValue Return Value - rc ===
 
Success If the function was successful, it returns nothing.
 
Failure If Index is invalid, a system halt occurs.
 
 
 
 
 
=== VDHPutSysValue - Parameters ===
 
'''Index'''(DD) Index of the system value to set. System value indexes are defined in VDMM.INC and listed in [[00822.htm|VDHQuerySysValue]].
 
'''Value'''(DD) New value for the system variable.
 
 
 
 
 
=== VDHPutSysValue - Purpose ===
 
Context Issues: This function can be called in the initialization or DOS session-task (DOS session creation) context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This service is intended for system virtual device drivers to export system constants, such as ROM memory size. The behavior of the system is undefined if this service is used for any other purpose.
 
 
 
 
 
=== VDHPutSysValue - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQueryFreePages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  the  total  amount  of  free  virtual  memory  in  bytes .
This  is  the  amount  of  memory  that  could  be  allocated  successfully .
* /
 
include  mvdm . inc
 
EXTERN    VDHQueryFreePages : NEAR
    DD  ?
 
PUSH          ;    Push
 
CALL      VDHQueryFree ;  Call  the  function </pre>
 
 
 
 
=== VDHQueryFreePages - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  the  total  amount  of  free  virtual  memory  in  bytes .
This  is  the  amount  of  memory  that  could  be  allocated  successfully .
* /
 
include  mvdm . inc
 
EXTERN    VDHQueryFreePages : NEAR
    DD  ?
 
PUSH          ;    Push
 
CALL      VDHQueryFree ;  Call  the  function </pre>
 
 
 
 
=== VDHQueryFreePages Parameter - ===
 
(DD) None.
 
 
 
 
 
=== VDHQueryFreePages Return Value - rc ===
 
Success If the function is successful, it returns the number of bytes of free virtual memory.
 
Failure If the function fails, it returns nothing.
 
 
 
 
 
=== VDHQueryFreePages - Parameters ===
 
(DD) None.
 
 
 
 
 
=== VDHQueryFreePages - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This is a system-wide value that is not specific to the virtual address space of the DOS session.
 
 
 
 
 
=== VDHQueryFreePages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQueryHookData ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  a  pointer  to  the  reference  data  created
during  the  call  to  VDHAllocHook .
* /
 
include  mvdm . inc
 
EXTERN    VDHQueryHookData : NEAR
HookHandle    DD  ?      ;    Hook  handle  from  VDHAllocHook
 
PUSH      HookHandle    ;    Push  HookHandle
 
CALL      VDHQueryHookData    ;  Call  the  function </pre>
 
 
 
 
=== VDHQueryHookData - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  a  pointer  to  the  reference  data  created
during  the  call  to  VDHAllocHook .
* /
 
include  mvdm . inc
 
EXTERN    VDHQueryHookData : NEAR
HookHandle    DD  ?      ;    Hook  handle  from  VDHAllocHook
 
PUSH      HookHandle    ;    Push  HookHandle
 
CALL      VDHQueryHookData    ;  Call  the  function </pre>
 
 
 
 
=== VDHQueryHookData Parameter - HookHandle ===
 
'''HookHandle'''(DD) Hook handle (from VDHAllocHook) for the hook to query.
 
 
 
 
 
=== VDHQueryHookData Return Value - rc ===
 
Success If the function is successful, it returns a pointer to the reference data block.
 
Failure If HookHandle is invalid or if there is no reference data (that is, the RefDataSize parameter for VDHAllocHook is ''0''), a system halt occurs.
 
 
 
 
 
=== VDHQueryHookData - Parameters ===
 
'''HookHandle'''(DD) Hook handle (from VDHAllocHook) for the hook to query.
 
 
 
 
 
=== VDHQueryHookData - Purpose ===
 
Context Issues: This function can be called in the initialization, task, or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHQueryHookData - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQueryLin ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  converts  a  16 : 16  ( Far16 )  address  to  a  0 : 32
address .
The  16 : 16  address  can  be  a  LDT - based  or  GDT - based  address .
The  function  is  also  callable  on  stack - based  addresses .
* /
 
include  mvdm . inc
 
EXTERN    VDHQueryLin : NEAR
Far16Addr    DD  ?      ;    16 : 16  addressto  be  converted
 
PUSH      Far16Addr    ;    Push  Far16Addr
 
CALL      VDHQueryLin    ;  Call  the  function </pre>
 
 
 
 
=== VDHQueryLin - Format ===
 
 
 
<pre class="western">/*
 
This  function  converts  a  16 : 16  ( Far16 )  address  to  a  0 : 32
address .
The  16 : 16  address  can  be  a  LDT - based  or  GDT - based  address .
The  function  is  also  callable  on  stack - based  addresses .
* /
 
include  mvdm . inc
 
EXTERN    VDHQueryLin : NEAR
Far16Addr    DD  ?      ;    16 : 16  addressto  be  converted
 
PUSH      Far16Addr    ;    Push  Far16Addr
 
CALL      VDHQueryLin    ;  Call  the  function </pre>
 
 
 
 
=== VDHQueryLin Parameter - Far16Addr ===
 
'''Far16Addr'''(DD) The 16:16 address to be converted to a 0:32 address.
 
 
 
 
 
=== VDHQueryLin Return Value - rc ===
 
Success If the function is successful, it returns the 0:32 address that corresponds to Far16Addr.
 
Failure If Far16Addr is an invalid selector, a system halt occurs.
 
 
 
 
 
=== VDHQueryLin - Parameters ===
 
'''Far16Addr'''(DD) The 16:16 address to be converted to a 0:32 address.
 
 
 
 
 
=== VDHQueryLin - Purpose ===
 
Context Issues: This function can be called in the initialization, task, or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This service does minimal checking on Far16Addr. The caller should make sure that Far16Addr is not invalid. If an invalid address is passed, this service can return an invalid address.
 
 
 
 
 
=== VDHQueryLin - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQueryKeyShift ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  called  by  the  virtual  mouse  device  driver  to  query
the  keyboard  shift  state  of  a  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHQueryKeyShift : NEAR
VDMHandle    DD  ?      ;    DOS  session  handle
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHQueryKeyShift    ;  Call  the  function </pre>
 
 
 
 
=== VDHQueryKeyShift - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  called  by  the  virtual  mouse  device  driver  to  query
the  keyboard  shift  state  of  a  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHQueryKeyShift : NEAR
VDMHandle    DD  ?      ;    DOS  session  handle
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHQueryKeyShift    ;  Call  the  function </pre>
 
 
 
 
=== VDHQueryKeyShift Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) DOS session handle.
 
 
 
 
 
=== VDHQueryKeyShift Return Value - rc ===
 
Returns a USHORT which is a bitmask that indicates the current key state:
 
Right Shift 1 <br />Left Shift 2 <br />Ctrl 4 <br />ALT 8 <br />Left Ctrl 100 <br />Left ALT 200 <br />Right Ctrl 400 <br />Right ALT 800
 
 
 
 
 
=== VDHQueryKeyShift - Parameters ===
 
'''VDMHandle'''(DD) DOS session handle.
 
 
 
 
 
=== VDHQueryKeyShift - Purpose ===
 
Context Issues: This function can be called only in the interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHQueryKeyShift - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQueryProperty ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  the  current  value  of  the  specified  DOS  Setting .
 
* /
 
include  mvdm . inc
 
EXTERN    VDHQueryProperty : NEAR
PropertyName    DD  ?      ;    Pointer  to  a  property  name
 
PUSH      PropertyName    ;    Push  PropertyName
 
CALL      VDHQueryProperty      ;  Call  the  function </pre>
 
 
 
 
=== VDHQueryProperty - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  the  current  value  of  the  specified  DOS  Setting .
 
* /
 
include  mvdm . inc
 
EXTERN    VDHQueryProperty : NEAR
PropertyName    DD  ?      ;    Pointer  to  a  property  name
 
PUSH      PropertyName    ;    Push  PropertyName
 
CALL      VDHQueryProperty      ;  Call  the  function </pre>
 
 
 
 
=== VDHQueryProperty Parameter - PropertyName ===
 
'''PropertyName'''(DD) Pointer to an ASCIIZ string containing the property name for which information is being sought. Maximum length is 40 characters, including the terminating NULL.
 
 
 
 
 
=== VDHQueryProperty Return Value - rc ===
 
Success The format of the return value for successful depends on the type of the property being queried:
 
VDMP_BOOL The return value is a BOOL (Boolean). A ''0''value represents FALSE and a nonzero value represents TRUE.
 
VDMP_INT The return value is a DD. It is guaranteed to be valid with respect to the bounding information specified in VDHRegisterVDD. Only the low half (DW) of the DD is significant. The high half is always ''0''.
 
VDMP_ENUM The return value is a pointer to a NULL-terminated string. The string is guaranteed to be one of those specified in VDHRegisterVDD.
 
VDMP_STRING The return value is a pointer to a NULL-terminated string. The string is guaranteed to be, at most, as long as the limit specified in VDHRegisterVDD.
 
VDMP_MLSTR The return value is a pointer to a NULL-terminated string. The string is guaranteed to be, at most, as long as the limit specified in VDHRegisterVDD.
 
'''Note:'''For property types VDMP_ENUM, VDMP_STRING, and VDMP_MLSTR, a pointer to the current value is returned to the virtual device driver, thereby avoiding a condition where an OS/2 process might be trying to change the same value. The virtual device driver calls VDHFreeMem to free the string after the virtual device driver is finished with it.
 
Failure If the function fails, it returns NULL for property types VDMP_ENUM , VDMP_STRING, and VDMP_MLSTR, if there is insufficient memory to create a copy of the string value. In this case, the virtual device driver uses the default property value. NULL is also returned if pszName is invalid or is not a registered virtual device driver name.
 
 
 
 
 
=== VDHQueryProperty - Parameters ===
 
'''PropertyName'''(DD) Pointer to an ASCIIZ string containing the property name for which information is being sought. Maximum length is 40 characters, including the terminating NULL.
 
 
 
 
 
=== VDHQueryProperty - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: All memory allocated by a virtual device driver for use by the terminating DOS session is freed by using VDHFreeMem.
 
Notes: A virtual device driver can assume that the property value is valid. The system validates all types, except VDMP_STRING and VDMP_MLSTR, by using the validation values passed on the call to VDHRegisterProperty. The string types are validated by calling the virtual device driver function registered through VDHRegisterProperty.
 
 
 
 
 
=== VDHQueryProperty - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQuerySel ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  the  selector  part  of  a  16 : 16  far  pointer
from  a  flat  0 : 32  address .
The  selector  is  in  the  Global  Descriptor  Table  ( GDT ) .
* /
 
include  mvdm . inc
 
EXTERN    VDHQuerySel : NEAR
VirtAddress    DD  ?      ;    0 : 32  virtual  address
 
PUSH      VirtAddress    ;    Push  VirtAddress
 
CALL      VDHQuerySel      ;  Call  the  function </pre>
 
 
 
 
=== VDHQuerySel - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  the  selector  part  of  a  16 : 16  far  pointer
from  a  flat  0 : 32  address .
The  selector  is  in  the  Global  Descriptor  Table  ( GDT ) .
* /
 
include  mvdm . inc
 
EXTERN    VDHQuerySel : NEAR
VirtAddress    DD  ?      ;    0 : 32  virtual  address
 
PUSH      VirtAddress    ;    Push  VirtAddress
 
CALL      VDHQuerySel      ;  Call  the  function </pre>
 
 
 
 
=== VDHQuerySel Parameter - VirtAddress ===
 
'''VirtAddress'''(DD) A 0:32 virtual address.
 
 
 
 
 
=== VDHQuerySel Return Value - rc ===
 
Success If the function is successful, it returns a nonzero selector.
 
Failure If the specified linear address is not in a virtual device driver data object, a system halt occurs.
 
 
 
 
 
=== VDHQuerySel - Parameters ===
 
'''VirtAddress'''(DD) A 0:32 virtual address.
 
 
 
 
 
=== VDHQuerySel - Purpose ===
 
Context Issues: This function can be called in the initialization and task context:
 
*During initialization time; query is allowed only on initialization and global data. <br />*Global, instance, and stack data are allowed during task time (typically DOS session creation time), but initialization data is not.
 
DOS Session Terminations: Selectors for virtual device driver instance data are destroyed when the DOS session terminates. The virtual device driver must ensure that any physical device driver that was given this kind of selector is finished with it.
 
Notes: This function works only on 0:32 addresses in virtual device driver data objects and stacks. Each virtual device driver data object is limited to a maximum of 64KB in size so that the following formula can be used. A virtual device driver that needs more than 64KB of a particular class (INIT , global, or instance) must use multiple objects.
 
Notice that the selectors for virtual device driver data are created to map starting at a 64KB linear address boundary. As a result, ''VDHQuerySel''needs to be called only once. The returned selector is valid for any memory in the particular object that contains the passed address, because the DOS Session Manager does not allow a virtual device driver data object to span a 64KB linear address boundary.
 
For virtual device driver instance data, this function returns a different GDT selector for each DOS session, and it can be called only in the context of a DOS session.
 
 
 
 
 
=== VDHQuerySel - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQuerySem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  queries  the  state  of  an  event  or  mutex  semaphore .
* /
 
include  mvdm . inc
 
EXTERN    VDHQuerySem : NEAR
SemHandle      DD  ?      ;    Handle  to  an  event  or  mutex  semaphore
SemStatePtr    DD  ?      ;    Pointer  to  a  VDHSEMSTATE  data  area
 
PUSH      SemHandle      ;    Push  SemHandle
PUSH      SemStatePtr    ;    Push  SemStatePtr
 
CALL      VDHQuerySem      ;  Call  the  function </pre>
 
 
 
 
=== VDHQuerySem - Format ===
 
 
 
<pre class="western">/*
 
This  function  queries  the  state  of  an  event  or  mutex  semaphore .
* /
 
include  mvdm . inc
 
EXTERN    VDHQuerySem : NEAR
SemHandle      DD  ?      ;    Handle  to  an  event  or  mutex  semaphore
SemStatePtr    DD  ?      ;    Pointer  to  a  VDHSEMSTATE  data  area
 
PUSH      SemHandle      ;    Push  SemHandle
PUSH      SemStatePtr    ;    Push  SemStatePtr
 
CALL      VDHQuerySem      ;  Call  the  function </pre>
 
 
 
 
=== VDHQuerySem Parameter - SemHandle ===
 
'''SemHandle'''(DD) Semaphore handle.
 
 
 
 
 
=== VDHQuerySem Parameter - SemStatePtr ===
 
'''SemStatePtr'''(DD) A pointer to the data area to be filled with the state of the semaphore.
 
SemStatePtr points to a variable defined in VDMM.INC and structured as follows:
 
<pre class="western">VDHSemState_s STRUC
        vss_SemType    DB  ?  ; VDH_EVENTSEM/VDH_MUTEXSEM
        vss_fOwned    DB  ?  ; 0 = Not Owned; 1 = Owned
        vss_fWaiter    DW  ?  ; 0 = No one waiting; 1 = Waiting
        vss_cRequest  DW  ?  ; Request count in mutex case
        vss_tid        DW  ?  ; TID of the owner, if owned
VDHSemState_s ENDS</pre>
 
 
 
 
 
 
=== VDHQuerySem Return Value - ===
 
None.
 
 
 
 
 
=== VDHQuerySem - Parameters ===
 
'''SemHandle'''(DD) Semaphore handle.
 
'''SemStatePtr'''(DD) A pointer to the data area to be filled with the state of the semaphore.
 
SemStatePtr points to a variable defined in VDMM.INC and structured as follows:
 
<pre class="western">VDHSemState_s STRUC
        vss_SemType    DB  ?  ; VDH_EVENTSEM/VDH_MUTEXSEM
        vss_fOwned    DB  ?  ; 0 = Not Owned; 1 = Owned
        vss_fWaiter    DW  ?  ; 0 = No one waiting; 1 = Waiting
        vss_cRequest  DW  ?  ; Request count in mutex case
        vss_tid        DW  ?  ; TID of the owner, if owned
VDHSemState_s ENDS</pre>
 
 
 
 
 
 
=== VDHQuerySem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for state checking services.
 
Notes: The validity of SemStatePtr is not checked. The calling program must pass the address of a valid data area.
 
 
 
 
 
=== VDHQuerySem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQuerySysValue ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  queries  a  system  value .
* /
 
include  mvdm . inc
 
EXTERN    VDHQuerySysValue : NEAR
VDMHandle    DD  ?      ;    Index  of  the  system  variable  handle  of  the  DOS  session
Index        DD  ?      ;    Index  values
 
PUSH      VDMHandle    ;    Push  VDMHandle
PUSH      Index        ;    Push  Index
 
CALL      VDHQuerySysValue    ;  Call  the  function </pre>
 
 
 
 
=== VDHQuerySysValue - Format ===
 
 
 
<pre class="western">/*
 
This  function  queries  a  system  value .
* /
 
include  mvdm . inc
 
EXTERN    VDHQuerySysValue : NEAR
VDMHandle    DD  ?      ;    Index  of  the  system  variable  handle  of  the  DOS  session
Index        DD  ?      ;    Index  values
 
PUSH      VDMHandle    ;    Push  VDMHandle
PUSH      Index        ;    Push  Index
 
CALL      VDHQuerySysValue    ;  Call  the  function </pre>
 
 
 
 
=== VDHQuerySysValue Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) Index of the system variable handle of the DOS session to query. A value of 0 (zero) indicates the current DOS session.
 
 
 
 
 
=== VDHQuerySysValue Parameter - Index ===
 
'''Index'''(DD) ''VDHQuerySysValue''index values (as defined in VDMM.INC) and descriptions:
 
<pre class="western">Global Values        Ordinal  Type  Units        Range
_____________        _______  ____  _____        _____
 
VDHGSV_DAY              0    DD    days          1 &lt; = x &lt; = 31
VDHGSV_MONTH            1    DD    months        1 &lt; = x &lt; = 12
VDHGSV_YEAR            2    DD    years        1980 &lt; = x &lt; = MAXULONG
VDHGSV_DAYOFWEEK        3    DD    days          0 &lt; = x &lt; = 6
VDHGSV_HOUR            4    DD    hours        0 &lt; = x &lt; = 24
VDHGSV_MINUTE          5    DD    minutes      0 &lt; = x &lt; = 60
VDHGSV_SECOND          6    DD    seconds      0 &lt; = x &lt; = 60
VDHGSV_HUNDREDTH        7    DD    1/100S        0 &lt; = x &lt; = 100
VDHGSV_SECONDS1970      8    DD    seconds      0 &lt; = x &lt; = MAXULONG
VDHGSV_TIMEZONE        9    DD    minutes      0 &lt; = x &lt; = MAXULONG
VDHGSV_MSECSBOOT        10    DD    milliseconds  0 &lt; = x &lt; = MAXULONG
VDHGSV_TIMERINTERVAL    11    DD    milliseconds  0 &lt; = x &lt; = 1000
VDHGSV_DYNVARIATION    12    DD                  TRUE(nonzero)/FALSE(0)
VDHGSV_MAXWAIT          13    DD    seconds      0 &lt; = x &lt; = MAXULONG
VDHGSV_MINTIMESLICE    14    DD    milliseconds  0 &lt; = x &lt; = MAXULONG
VDHGSV_MAXTIMESLICE    15    DD    milliseconds  0 &lt; = x &lt; = MAXULONG</pre>
 
 
<pre class="western">Global Values        Ordinal  Type  Units        Range
_____________        _______  ____  _____        _____
 
VDHGSV_YIELD            16    DD                  TRUE(nonzero)/FALSE(0)
VDHGSV_TCYIELD          17    DD                  TRUE(nonzero)/FALSE(0)
VDHGSV_VERMAJOR        18    DD                  0 &lt; = x &lt; = MAXULONG
VDHGSV_VERMINOR        19    DD                  0 &lt; = x &lt; = MAXULONG
VDHGSV_VERREVISION      20    DD                  0 &lt; = x &lt; = 255
VDHGSV_MACHINETYPE      21    DD                  MACHINE_TYPE_
VDHGSV_BLACKHOLEADDR    22    DD    bytes        0 &lt; = x &lt; = MAXULONG
VDHGSV_BLACKHOLESIZE    23    DD    bytes        0 &lt; = x &lt; = MAXULONG
VDHGSV_FGNDSESSIONID    24    DD                  0 &lt; = x &lt; = MAXSESSIONS
VDHGSV_ARPLADDR        29    DD
VDHGSV_MACHINEINFO      30    DD                  Pointer to System
                                                  Configuration table
VDHGSV_PPOSREGS        31    DD                  Pointer to POS Regs
                                                  structure
VDHGSV_PICMASK          32    DD                  Original PIC mask values
 
 
Local Values        Ordinal  Type  Units        Range
____________        _______  ____  _____        _____
 
VDHLSV_HVDM          4096    DD
VDHLSV_PID            4097    DD
VDHLSV_PCRF          4098    DD
VDHLSV_SESSIONID      4099    DD                  N &lt; = x &lt; MAXSESSIONS
VDHLSV_FOREGROUND    4100    DD                  TRUE(nonzero)/FALSE(0)
VDHLSV_RMSIZE        4101    DD    KB            0 &lt; x &lt; = 640
VDHLSV_CODEPAGEID    4102    DD                  See DosGetCP
VDHLSV_PRIORITYCLASS  4103    DD                  See VDHSetPriority
VDHLSV_PRIORITYLEVEL  4104    DD                  See VDHSetPriority
VDHLSV_VPICBASE      4105    DD</pre>
 
 
 
 
 
 
=== VDHQuerySysValue Return Value - rc ===
 
Success If the function is successful, it returns the value of the system variable. If the value is 0 and ''VDHGetError''returns 0, then 0 is the correct value.
 
Failure If ''VDMHandle''or ''Index''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHQuerySysValue - Parameters ===
 
'''VDMHandle'''(DD) Index of the system variable handle of the DOS session to query. A value of 0 (zero) indicates the current DOS session.
 
'''Index'''(DD) ''VDHQuerySysValue''index values (as defined in VDMM.INC) and descriptions:
 
<pre class="western">Global Values        Ordinal  Type  Units        Range
_____________        _______  ____  _____        _____
 
VDHGSV_DAY              0    DD    days          1 &lt; = x &lt; = 31
VDHGSV_MONTH            1    DD    months        1 &lt; = x &lt; = 12
VDHGSV_YEAR            2    DD    years        1980 &lt; = x &lt; = MAXULONG
VDHGSV_DAYOFWEEK        3    DD    days          0 &lt; = x &lt; = 6
VDHGSV_HOUR            4    DD    hours        0 &lt; = x &lt; = 24
VDHGSV_MINUTE          5    DD    minutes      0 &lt; = x &lt; = 60
VDHGSV_SECOND          6    DD    seconds      0 &lt; = x &lt; = 60
VDHGSV_HUNDREDTH        7    DD    1/100S        0 &lt; = x &lt; = 100
VDHGSV_SECONDS1970      8    DD    seconds      0 &lt; = x &lt; = MAXULONG
VDHGSV_TIMEZONE        9    DD    minutes      0 &lt; = x &lt; = MAXULONG
VDHGSV_MSECSBOOT        10    DD    milliseconds  0 &lt; = x &lt; = MAXULONG
VDHGSV_TIMERINTERVAL    11    DD    milliseconds  0 &lt; = x &lt; = 1000
VDHGSV_DYNVARIATION    12    DD                  TRUE(nonzero)/FALSE(0)
VDHGSV_MAXWAIT          13    DD    seconds      0 &lt; = x &lt; = MAXULONG
VDHGSV_MINTIMESLICE    14    DD    milliseconds  0 &lt; = x &lt; = MAXULONG
VDHGSV_MAXTIMESLICE    15    DD    milliseconds  0 &lt; = x &lt; = MAXULONG</pre>
 
 
<pre class="western">Global Values        Ordinal  Type  Units        Range
_____________        _______  ____  _____        _____
 
VDHGSV_YIELD            16    DD                  TRUE(nonzero)/FALSE(0)
VDHGSV_TCYIELD          17    DD                  TRUE(nonzero)/FALSE(0)
VDHGSV_VERMAJOR        18    DD                  0 &lt; = x &lt; = MAXULONG
VDHGSV_VERMINOR        19    DD                  0 &lt; = x &lt; = MAXULONG
VDHGSV_VERREVISION      20    DD                  0 &lt; = x &lt; = 255
VDHGSV_MACHINETYPE      21    DD                  MACHINE_TYPE_
VDHGSV_BLACKHOLEADDR    22    DD    bytes        0 &lt; = x &lt; = MAXULONG
VDHGSV_BLACKHOLESIZE    23    DD    bytes        0 &lt; = x &lt; = MAXULONG
VDHGSV_FGNDSESSIONID    24    DD                  0 &lt; = x &lt; = MAXSESSIONS
VDHGSV_ARPLADDR        29    DD
VDHGSV_MACHINEINFO      30    DD                  Pointer to System
                                                  Configuration table
VDHGSV_PPOSREGS        31    DD                  Pointer to POS Regs
                                                  structure
VDHGSV_PICMASK          32    DD                  Original PIC mask values
 
 
Local Values        Ordinal  Type  Units        Range
____________        _______  ____  _____        _____
 
VDHLSV_HVDM          4096    DD
VDHLSV_PID            4097    DD
VDHLSV_PCRF          4098    DD
VDHLSV_SESSIONID      4099    DD                  N &lt; = x &lt; MAXSESSIONS
VDHLSV_FOREGROUND    4100    DD                  TRUE(nonzero)/FALSE(0)
VDHLSV_RMSIZE        4101    DD    KB            0 &lt; x &lt; = 640
VDHLSV_CODEPAGEID    4102    DD                  See DosGetCP
VDHLSV_PRIORITYCLASS  4103    DD                  See VDHSetPriority
VDHLSV_PRIORITYLEVEL  4104    DD                  See VDHSetPriority
VDHLSV_VPICBASE      4105    DD</pre>
 
 
 
 
 
 
=== VDHQuerySysValue - Purpose ===
 
Context Issues: This function can be called in any context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Systems values are of two classes, global and per-DOS session. These classes are distinguished by the prefix of the index name. Variables with prefixes of ''VDHGSV_''are global. Variables with a ''VDHLSV_''prefix are per-DOS session.
 
 
 
 
 
=== VDHQuerySysValue - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHQueryVIRQ ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  returns  information  about  the  virtual  mask ,  interrupt
request  flag ,  interrupt  in - service  flag ,  and  pending  virtual  device  driver
Interrupt  Return  ( IRET )  handlers  for  the  specified  IRQ ,  device ,
or  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHQueryVIRQ : NEAR
VDMHandle    DD  ?      ;    IRQ  handle  from  DOS  session  handle
IRQHandle    DD  ?      ;    IRQ  handle  from  VDHOpenVIRQ
 
PUSH      VDMHandle    ;    Push  VDMHandle
PUSH      IRQHandle    ;    Push  IRQHandle
 
CALL      VDHQueryVIRQ    ;  Call  the  function </pre>
 
 
 
 
=== VDHQueryVIRQ - Format ===
 
 
 
<pre class="western">/*
 
This  function  returns  information  about  the  virtual  mask ,  interrupt
request  flag ,  interrupt  in - service  flag ,  and  pending  virtual  device  driver
Interrupt  Return  ( IRET )  handlers  for  the  specified  IRQ ,  device ,
or  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHQueryVIRQ : NEAR
VDMHandle    DD  ?      ;    IRQ  handle  from  DOS  session  handle
IRQHandle    DD  ?      ;    IRQ  handle  from  VDHOpenVIRQ
 
PUSH      VDMHandle    ;    Push  VDMHandle
PUSH      IRQHandle    ;    Push  IRQHandle
 
CALL      VDHQueryVIRQ    ;  Call  the  function </pre>
 
 
 
 
=== VDHQueryVIRQ Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) IRQ handle from ''VDHOpenVIRQ''DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
 
 
 
 
=== VDHQueryVIRQ Parameter - IRQHandle ===
 
'''IRQHandle'''(DD) IRQ handle from ''VDHOpenVIRQ''.
 
 
 
 
 
=== VDHQueryVIRQ Return Value - rc ===
 
Success If the function is successful, it returns the IRQ status as a DD of flag bits:
 
VPICQ_REQUEST_PENDING Request is pending for the queried IRQ <br />VPICQ_IN_SERVICE Queried IRQ is in service <br />VPICQ_VIRT_MASK Mask is turned ON for the queried IRQ <br />VPICQ_STAT_IRET_PENDING IRET is pending for the queried IRQ.
 
Failure If ''VDMHandle''or ''IRQHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHQueryVIRQ - Parameters ===
 
'''VDMHandle'''(DD) IRQ handle from ''VDHOpenVIRQ''DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
'''IRQHandle'''(DD) IRQ handle from ''VDHOpenVIRQ''.
 
 
 
 
 
=== VDHQueryVIRQ - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHQueryVIRQ - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRaiseException ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  to  raise  an  exception ,  which  is  reflected  to  a
DOS  session  as  if  the  exception  were  caused  by  the  hardware .
* /
 
include  mvdm . inc
 
EXTERN    VDHRaiseException : NEAR
Exception    DD  ?      ;    An  exception  number
ErrorCode    DD  ?      ;    Error  code  for  the  exception
ExtraCode    DD  ?      ;    Extra  error  code
 
PUSH      Exception    ;    Push  Exception
PUSH      ErrorCode    ;    Push  ErrorCode
PUSH      ExtraCode    ;    Push  ExtraCode
 
CALL      VDHRaiseException    ;  Call  the  function </pre>
 
 
 
 
=== VDHRaiseException - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  to  raise  an  exception ,  which  is  reflected  to  a
DOS  session  as  if  the  exception  were  caused  by  the  hardware .
* /
 
include  mvdm . inc
 
EXTERN    VDHRaiseException : NEAR
Exception    DD  ?      ;    An  exception  number
ErrorCode    DD  ?      ;    Error  code  for  the  exception
ExtraCode    DD  ?      ;    Extra  error  code
 
PUSH      Exception    ;    Push  Exception
PUSH      ErrorCode    ;    Push  ErrorCode
PUSH      ExtraCode    ;    Push  ExtraCode
 
CALL      VDHRaiseException    ;  Call  the  function </pre>
 
 
 
 
=== VDHRaiseException Parameter - Exception ===
 
'''Exception'''(DD) An exception number that might be caused by the 80386 microprocessor.
 
 
 
 
 
=== VDHRaiseException Parameter - ErrorCode ===
 
'''ErrorCode'''(DD) Error code for the exception defined for the 80386 microprocessor.
 
 
 
 
 
=== VDHRaiseException Parameter - ExtraCode ===
 
'''ExtraCode'''(DD) Extra error code for DPMI 1.0 page faults.
 
 
 
 
 
=== VDHRaiseException Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHRaiseException - Parameters ===
 
'''Exception'''(DD) An exception number that might be caused by the 80386 microprocessor.
 
'''ErrorCode'''(DD) Error code for the exception defined for the 80386 microprocessor.
 
'''ExtraCode'''(DD) Extra error code for DPMI 1.0 page faults.
 
 
 
 
 
=== VDHRaiseException - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHRaiseException - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRead ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  reads  bytes  from  a  file  or  device  previously  opened
by  VDHOpen .
* /
 
include  mvdm . inc
 
EXTERN    VDHRead : NEAR
FileHandle      DW  ?      ;    Handle  to  the  file  or  device  to  read
ReadBufferPtr    DD  ?      ;    Address  of  the  buffer  to  store  the  bytes  read
NumBytes        DD  ?      ;    Number  of  bytes  to  read
 
PUSH      FileHandle      ;    Push  FileHandle
PUSH      ReadBufferPtr    ;    Push  ReadBufferPtr
PUSH      NumBytes        ;    Push  NumBytes
 
CALL      VDHRead        ;  Call  the  function </pre>
 
 
 
 
=== VDHRead - Format ===
 
 
 
<pre class="western">/*
 
This  function  reads  bytes  from  a  file  or  device  previously  opened
by  VDHOpen .
* /
 
include  mvdm . inc
 
EXTERN    VDHRead : NEAR
FileHandle      DW  ?      ;    Handle  to  the  file  or  device  to  read
ReadBufferPtr    DD  ?      ;    Address  of  the  buffer  to  store  the  bytes  read
NumBytes        DD  ?      ;    Number  of  bytes  to  read
 
PUSH      FileHandle      ;    Push  FileHandle
PUSH      ReadBufferPtr    ;    Push  ReadBufferPtr
PUSH      NumBytes        ;    Push  NumBytes
 
CALL      VDHRead        ;  Call  the  function </pre>
 
 
 
 
=== VDHRead Parameter - FileHandle ===
 
'''FileHandle'''(DW) Handle to the file or device to read.
 
 
 
 
 
=== VDHRead Parameter - ReadBufferPtr ===
 
'''ReadBufferPtr'''(DD) Address of the buffer to store the bytes read.
 
 
 
 
 
=== VDHRead Parameter - NumBytes ===
 
'''NumBytes'''(DD) Number of bytes to read.
 
 
 
 
 
=== VDHRead Return Value - rc ===
 
Success If the function is successful, it returns a count of the number of bytes read; this can be equal to 0 (zero).
 
Failure If the function fails, it returns 0FFFFFFFFH. ''VDHGetError''should be called to determine the nature of the problem. If ''FileHandle''is invalid or this function is called in any context except DOS session-task, a system halt occurs.
 
 
 
 
 
=== VDHRead - Parameters ===
 
'''FileHandle'''(DW) Handle to the file or device to read.
 
'''ReadBufferPtr'''(DD) Address of the buffer to store the bytes read.
 
'''NumBytes'''(DD) Number of bytes to read.
 
 
 
 
 
=== VDHRead - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHRead - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHReadUBuf ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  to  read  from  protected - mode  address  space  as  if
the  read  were  done  at  Ring  3 .
This  means  any  other  faults  are  trapped .
All  faults  are  passed  on  to  the  DOS  session  application  handler  through
VDHRaiseException .
* /
 
include  mvdm . inc
 
EXTERN    VDHReadUBuf : NEAR
DestBuffer      DD  ?      ;    Destination  buffer  for  copy .
ByteCount        DD  ?      ;    Count  of  bytes
Selector        DW  ?      ;    Application  selector
OffsetPointer    DD  ?      ;    Address  of  the  variable  containing  the  offset
Flag              DD  ?      ;    Checking  controls  flag
 
PUSH      DestBuffer      ;    Push  DestBuffer
PUSH      ByteCount        ;    Push  ByteCount
PUSH      Selector        ;    Push  Selector
PUSH      OffsetPointer    ;    Push  OffsetPointer
PUSH      Flag              ;    Push  Flag
 
CALL      VDHReadUBuf        ;  Call  the  function </pre>
 
 
 
 
=== VDHReadUBuf - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  to  read  from  protected - mode  address  space  as  if
the  read  were  done  at  Ring  3 .
This  means  any  other  faults  are  trapped .
All  faults  are  passed  on  to  the  DOS  session  application  handler  through
VDHRaiseException .
* /
 
include  mvdm . inc
 
EXTERN    VDHReadUBuf : NEAR
DestBuffer      DD  ?      ;    Destination  buffer  for  copy .
ByteCount        DD  ?      ;    Count  of  bytes
Selector        DW  ?      ;    Application  selector
OffsetPointer    DD  ?      ;    Address  of  the  variable  containing  the  offset
Flag              DD  ?      ;    Checking  controls  flag
 
PUSH      DestBuffer      ;    Push  DestBuffer
PUSH      ByteCount        ;    Push  ByteCount
PUSH      Selector        ;    Push  Selector
PUSH      OffsetPointer    ;    Push  OffsetPointer
PUSH      Flag              ;    Push  Flag
 
CALL      VDHReadUBuf        ;  Call  the  function </pre>
 
 
 
 
=== VDHReadUBuf Parameter - DestBuffer ===
 
'''DestBuffer'''(DD) Destination buffer for copy.
 
 
 
 
 
=== VDHReadUBuf Parameter - ByteCount ===
 
'''ByteCount'''(DD) Count of bytes.
 
 
 
 
 
=== VDHReadUBuf Parameter - Selector ===
 
'''Selector'''(DW) Application selector.
 
 
 
 
 
=== VDHReadUBuf Parameter - OffsetPointer ===
 
'''OffsetPointer'''(DD) Address of the variable containing the offset for the start of the read.
 
 
 
 
 
=== VDHReadUBuf Parameter - Flag ===
 
'''Flag'''(DD) Flag containing checking controls.
 
Possible values are:
 
VPM_PROT_READ Check for read. <br />VPM_PROT_WRITE Check for write. <br />VPM_FAULT_IF_SU_SET Fault, if supervisor pages. <br />VPM_FAULT_IF_RO Fault, if writing to read-only descriptor. <br />VPM_SEL_PRESENT Caller knows descriptor is present. <br />VPM_SEL_WRITEABLE Caller knows descriptor is writable. <br />VPM_SEL_IS_SS Selector is client's stack. <br />VPM_XCPTRET_ALT After exception, return to alternate mode. For example, if the client was in protected mode when the service was called, return in V86 mode after the exception is handled.
 
 
 
 
 
=== VDHReadUBuf Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 if a bad address reference is causing the fault. In this case, ''OffsetPointer''is updated with the address of the fault. For selector faults, ''OffsetPointer''is unchanged.
 
 
 
 
 
=== VDHReadUBuf - Parameters ===
 
'''DestBuffer'''(DD) Destination buffer for copy.
 
'''ByteCount'''(DD) Count of bytes.
 
'''Selector'''(DW) Application selector.
 
'''OffsetPointer'''(DD) Address of the variable containing the offset for the start of the read.
 
'''Flag'''(DD) Flag containing checking controls.
 
Possible values are:
 
VPM_PROT_READ Check for read. <br />VPM_PROT_WRITE Check for write. <br />VPM_FAULT_IF_SU_SET Fault, if supervisor pages. <br />VPM_FAULT_IF_RO Fault, if writing to read-only descriptor. <br />VPM_SEL_PRESENT Caller knows descriptor is present. <br />VPM_SEL_WRITEABLE Caller knows descriptor is writable. <br />VPM_SEL_IS_SS Selector is client's stack. <br />VPM_XCPTRET_ALT After exception, return to alternate mode. For example, if the client was in protected mode when the service was called, return in V86 mode after the exception is handled.
 
 
 
 
 
=== VDHReadUBuf - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: If the routine fails, the caller must clean up and exit so that the exception can be simulated to the user. Supervisor pages can be read without faults to avoid the overhead of checking.
 
 
 
 
 
=== VDHReadUBuf - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHReallocPages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  expands  or  shrinks  a  memory  object .
* /
 
include  mvdm . inc
 
EXTERN    VDHReallocPages : NEAR
ObjectAddress    DD  ?      ;    Address  of  the  memory  object  to  resize
NumPages        DD  ?      ;    New  size  of  the  memory  object  ( in  4KB  pages )
Reserved        DD  ?      ;    Must  be  zero
 
PUSH      ObjectAddress    ;    Push  ObjectAddress
PUSH      NumPages        ;    Push  NumPages
PUSH      Reserved        ;    Push  Reserved
 
CALL      VDHReallocPages        ;  Call  the  function </pre>
 
 
 
 
=== VDHReallocPages - Format ===
 
 
 
<pre class="western">/*
 
This  function  expands  or  shrinks  a  memory  object .
* /
 
include  mvdm . inc
 
EXTERN    VDHReallocPages : NEAR
ObjectAddress    DD  ?      ;    Address  of  the  memory  object  to  resize
NumPages        DD  ?      ;    New  size  of  the  memory  object  ( in  4KB  pages )
Reserved        DD  ?      ;    Must  be  zero
 
PUSH      ObjectAddress    ;    Push  ObjectAddress
PUSH      NumPages        ;    Push  NumPages
PUSH      Reserved        ;    Push  Reserved
 
CALL      VDHReallocPages        ;  Call  the  function </pre>
 
 
 
 
=== VDHReallocPages Parameter - ObjectAddress ===
 
'''ObjectAddress'''(DD) Address of the memory object to reallocate or resize.
 
 
 
 
 
=== VDHReallocPages Parameter - NumPages ===
 
'''NumPages'''(DD) The new size of the memory object (in 4KB pages).
 
 
 
 
 
=== VDHReallocPages Parameter - Reserved ===
 
'''Reserved'''(DD) Must be set to zero.
 
 
 
 
 
=== VDHReallocPages Return Value - rc ===
 
Success If the function is successful, it returns that address of the reallocated memory block.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If the memory object at ''ObjectAddress''was not allocated by ''VDHAllocPages''or ''VDHReallocPages'', or if the ''NumPages''or ''Reserved''parameters are invalid, a system halt occurs.
 
 
 
 
 
=== VDHReallocPages - Parameters ===
 
'''ObjectAddress'''(DD) Address of the memory object to reallocate or resize.
 
'''NumPages'''(DD) The new size of the memory object (in 4KB pages).
 
'''Reserved'''(DD) Must be set to zero.
 
 
 
 
 
=== VDHReallocPages - Purpose ===
 
Context Issues: This function can be called in the initialization or task context.
 
DOS Session Terminations: Any allocations that are not in the terminating DOS session's private area must be released by using ''VDHFreePages''.
 
Notes: When an allocation made with ''VDHAllocPages''is shrunk by ''VDHReallocPages'', the linear range between the end of the allocation and the original end of the allocation remains available for object growth without movement. If the linear range encompassed by the new size was reserved ( with ''VDHReservePages''), reallocation occurs without movement. Reallocation also succeeds without movement if the object was larger than the desired size since it last moved. Regardless of ''VDHReallocPages''activity, all pages in the allocation retain the same properties, that is, fixed, system, and physical.
 
 
 
 
 
=== VDHReallocPages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRegisterAPI ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  to  register  a  virtual  device  driver ' s  API  handler
that  can  be  called  by  a  DOS  or  DPMI  application  in  the  DOS  session .
A  V86 - mode  or  protected - mode  ( or  both )  API  handler  is  set  for  a
particular  virtual  device  driver .
Each  virtual  device  driver  must  register  with  a  unique  virtual  device  driver  name .
This  service  provides  a  mechanism  for  DOS  applications  to
communicate  directly  with  the  virtual  device  driver .
* /
 
include  mvdm . inc
 
EXTERN    VDHRegisterAPI : NEAR
VDDName      DD  ?      ;    Pointer  to  the  name  of  the  virtual  device  driver
pfnV86Hook    DD  ?      ;    V86 - mode  hook  routine  address
pfnVPMHook    DD  ?      ;    VPM - mode  hook  routine  address
 
PUSH      VDDName      ;    Push  VDDName
PUSH      pfnV86Hook    ;    Push  pfnV86Hook
PUSH      pfnVPMHook    ;    Push  pfnVPMHook
 
CALL      VDHRegisterAPI    ;  Call  the  function </pre>
 
 
 
 
=== VDHRegisterAPI - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  to  register  a  virtual  device  driver ' s  API  handler
that  can  be  called  by  a  DOS  or  DPMI  application  in  the  DOS  session .
A  V86 - mode  or  protected - mode  ( or  both )  API  handler  is  set  for  a
particular  virtual  device  driver .
Each  virtual  device  driver  must  register  with  a  unique  virtual  device  driver  name .
This  service  provides  a  mechanism  for  DOS  applications  to
communicate  directly  with  the  virtual  device  driver .
* /
 
include  mvdm . inc
 
EXTERN    VDHRegisterAPI : NEAR
VDDName      DD  ?      ;    Pointer  to  the  name  of  the  virtual  device  driver
pfnV86Hook    DD  ?      ;    V86 - mode  hook  routine  address
pfnVPMHook    DD  ?      ;    VPM - mode  hook  routine  address
 
PUSH      VDDName      ;    Push  VDDName
PUSH      pfnV86Hook    ;    Push  pfnV86Hook
PUSH      pfnVPMHook    ;    Push  pfnVPMHook
 
CALL      VDHRegisterAPI    ;  Call  the  function </pre>
 
 
 
 
=== VDHRegisterAPI Parameter - VDDName ===
 
'''VDDName'''(DD) Pointer to the name of the virtual device driver. Maximum length is MAXLENXDD.
 
 
 
 
 
=== VDHRegisterAPI Parameter - pfnV86Hook ===
 
'''pfnV86Hook'''(DD) V86-mode hook routine address (NULL if no V86-mode handler is needed).
 
 
 
 
 
=== VDHRegisterAPI Parameter - pfnVPMHook ===
 
'''pfnVPMHook'''(DD) VPM-mode hook routine address (NULL if no VPM-mode handler is needed).
 
 
 
 
 
=== VDHRegisterAPI Return Value - rc ===
 
Success Returns TRUE
 
Failure Returns FALSE
 
 
 
 
 
=== VDHRegisterAPI - Parameters ===
 
'''VDDName'''(DD) Pointer to the name of the virtual device driver. Maximum length is MAXLENXDD.
 
'''pfnV86Hook'''(DD) V86-mode hook routine address (NULL if no V86-mode handler is needed).
 
'''pfnVPMHook'''(DD) VPM-mode hook routine address (NULL if no VPM-mode handler is needed).
 
 
 
 
 
=== VDHRegisterAPI - Purpose ===
 
Context Issues: This function can only be called in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function. The hook(s) are freed when the DOS session is terminated .
 
Notes:
 
Hook routine:
 
<pre class="western">HookRoutine PROC NEAR
; PARAMETERS
;    ENTRY    [ESP + 8] - p - reserved
;            [ESP + 4] - pcrf - pointer
;            to client register frame
;    EXIT    None
;    CONTEXT  DOS session-task</pre>
DOS or DPMI applications issue the following INT 2F calls to determine if they are running under OS/2, and then get the virtual device driver API entry point.
 
Get OS/2 version (DOS or DPMI applications can use this INT 2F call to get the OS/2 version):
 
<pre class="western">    ENTRY    AX = 0x4010
    EXIT      If OS/2 is running:
                  AX = 0
                  BX = OS/2 version (example:BX = 1400 for 2.0)
              If OS/2 is not present, AX is unchanged</pre>
Get virtual device driver API entry points. DOS or DPMI applications can use this INT 2F call to get the address to call the virtual device driver entry points. If the INT 2F is issued in V86 mode, an address that calls the V86 virtual device driver API handler is returned. If the INT 2F call is issued in protected-mode, an address that corresponds to the protected- mode API handler is returned.
 
<pre class="western">    ENTRY    AX = 0x4011
              DS:(E)SI = pointer to ASCIIZ name registered
                                with VDHRegisterAPI
    EXIT      If VDD API handler exists:
                  ES:DI = address to call to invoke handler
              If handler is not registered:
                  ES:DI = NULL</pre>
The DOS or DPMI application can then issue a far call to the address returned to invoke the virtual device driver API handler.
 
 
 
 
 
=== VDHRegisterAPI - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRegisterDMAChannel ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  by  virtual  device  drivers  to  register  with
the  virtual  DMA  device  driver  ( VDMA )  to  get  the  ownership  of  a  DMA  channel .
* /
 
include  mvdm . inc
 
EXTERN    VDHRegisterDMAChannel : NEAR
DMAChannel        DD  ?      ;    DMA  channel
DMAHandlerFunc    DD  ?      ;    The  virtual  device  driver ' s  DMA - handling  routine
 
PUSH      DMAChannel        ;    Push  DMAChannel
PUSH      DMAHandlerFunc    ;    Push  DMAHandlerFunc
 
CALL      VDHRegisterDMAChannel        ;  Call  the  function </pre>
 
 
 
 
=== VDHRegisterDMAChannel - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  by  virtual  device  drivers  to  register  with
the  virtual  DMA  device  driver  ( VDMA )  to  get  the  ownership  of  a  DMA  channel .
* /
 
include  mvdm . inc
 
EXTERN    VDHRegisterDMAChannel : NEAR
DMAChannel        DD  ?      ;    DMA  channel
DMAHandlerFunc    DD  ?      ;    The  virtual  device  driver ' s  DMA - handling  routine
 
PUSH      DMAChannel        ;    Push  DMAChannel
PUSH      DMAHandlerFunc    ;    Push  DMAHandlerFunc
 
CALL      VDHRegisterDMAChannel        ;  Call  the  function </pre>
 
 
 
 
=== VDHRegisterDMAChannel Parameter - DMAChannel ===
 
'''DMAChannel'''(DD) DMA channel.
 
 
 
 
 
=== VDHRegisterDMAChannel Parameter - DMAHandlerFunc ===
 
'''DMAHandlerFunc'''(DD) The virtual device driver's DMA-handler function.
 
The interface for the DMA-handler routine is as follows:
 
<pre class="western">DMAHandler  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm  - DOS session requesting DMA
;          [ESP + 4] - iEvent - VDD_DMA_MASKOFF (Start DMA, Event)
;                                VDD_DMA_MASK    (Stop  DMA, Event)
;    EXIT  SUCCESS - Returns nonzero in EAX
;                    If VDD_DMA_MASKOFF,
;                        the virtual DMA device driver will program the DMA
;                    If VDD_DMA_MASK, don't care
;          FAILURE - Returns 0 (zero) in EAX</pre>
 
 
 
 
 
 
=== VDHRegisterDMAChannel Return Value - rc ===
 
Success If the function is successful, it returns 1.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem.
 
 
 
 
 
=== VDHRegisterDMAChannel - Parameters ===
 
'''DMAChannel'''(DD) DMA channel.
 
'''DMAHandlerFunc'''(DD) The virtual device driver's DMA-handler function.
 
The interface for the DMA-handler routine is as follows:
 
<pre class="western">DMAHandler  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm  - DOS session requesting DMA
;          [ESP + 4] - iEvent - VDD_DMA_MASKOFF (Start DMA, Event)
;                                VDD_DMA_MASK    (Stop  DMA, Event)
;    EXIT  SUCCESS - Returns nonzero in EAX
;                    If VDD_DMA_MASKOFF,
;                        the virtual DMA device driver will program the DMA
;                    If VDD_DMA_MASK, don't care
;          FAILURE - Returns 0 (zero) in EAX</pre>
 
 
 
 
 
 
=== VDHRegisterDMAChannel - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: In the case of VDD_DMA_MASKOFF, the virtual device driver gets the hardware ownership and unhooks all the ports. If hardware ownership is not available immediately, it blocks the DOS session. On VDD_DMA_MASK, the virtual device driver returns the ownership and hooks back the ports.
 
If the DOS application programs the hardware handled by a virtual device driver first, and then programs the DMA, this virtual device driver receives ownership of hardware, unhooks all ports on first port access, and arms a timer for a safe period. This is a preventive measure to protect the system from errant I/O to DMA ports. If the timer fires, the virtual device driver releases the hardware. In this case, the virtual device driver does nothing when the virtual DMA device driver later calls with VDD_DMA_MASKOFF .
 
It is the virtual device driver's responsibility (in DMAHandlerFunc) to handle the unavailability of hardware ownership. This means the virtual device driver must put up the pop-up and suspend (or terminate) the DOS session. The virtual device driver passes the interrupt notification to the virtual DMA device driver before simulating that interrupt to the DOS session, if it owns the hardware.
 
In between VDD_DMA_MASKOFF and VDD_DMA_MASK events, the virtual DMA device driver always returns the physical DMA state, if the application polls its status or transfer count. This is appropriate because the virtual device driver owns the device during this period. VDD_DMA_MASK event notification takes place before actually masking the register in DMA. VDD_DMA_MASKOFF takes place after masking off the DMA.
 
DMA Channel 4 is not supported.
 
 
 
 
 
=== VDHRegisterDMAChannel - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRegisterProperty ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  registers  a  virtual  device  driver  property  with  the  DOS  Session  Manager .
* /
 
include  mvdm . inc
 
EXTERN    VDHRegisterProperty : NEAR
PropertyName      DD  ?      ;    Property  name  pointer
Reserved          DD  ?      ;    Must  be  set  to  0
Reserved          DD  ?      ;    Must  be  set  to  0
PropertyType      DW  ?      ;    Property  type
PropertyOrdinal    DW  ?      ;    Property  ordinal
PropertyFlag      DD  ?      ;    Property  flag
DefaultValue      DD  ?      ;    Default  value  of  the  property
ValidationData    DD  ?      ;    Validation  data
ValidationFunc    DD  ?      ;    Pointer  to  a  virtual  device  driver  property  function
 
PUSH      PropertyName      ;    Push  PropertyName
PUSH      Reserved          ;    Push  Reserved
PUSH      Reserved          ;    Push  Reserved
PUSH      PropertyType      ;    Push  PropertyType
PUSH      PropertyOrdinal    ;    Push  PropertyOrdinal
PUSH      PropertyFlag      ;    Push  PropertyFlag
PUSH      DefaultValue      ;    Push  DefaultValue
PUSH      ValidationData    ;    Push  ValidationData
PUSH      ValidationFunc    ;    Push  ValidationFunc
 
CALL      VDHRegisterProperty          ;  Call  the  function </pre>
 
 
 
 
=== VDHRegisterProperty - Format ===
 
 
 
<pre class="western">/*
 
This  function  registers  a  virtual  device  driver  property  with  the  DOS  Session  Manager .
* /
 
include  mvdm . inc
 
EXTERN    VDHRegisterProperty : NEAR
PropertyName      DD  ?      ;    Property  name  pointer
Reserved          DD  ?      ;    Must  be  set  to  0
Reserved          DD  ?      ;    Must  be  set  to  0
PropertyType      DW  ?      ;    Property  type
PropertyOrdinal    DW  ?      ;    Property  ordinal
PropertyFlag      DD  ?      ;    Property  flag
DefaultValue      DD  ?      ;    Default  value  of  the  property
ValidationData    DD  ?      ;    Validation  data
ValidationFunc    DD  ?      ;    Pointer  to  a  virtual  device  driver  property  function
 
PUSH      PropertyName      ;    Push  PropertyName
PUSH      Reserved          ;    Push  Reserved
PUSH      Reserved          ;    Push  Reserved
PUSH      PropertyType      ;    Push  PropertyType
PUSH      PropertyOrdinal    ;    Push  PropertyOrdinal
PUSH      PropertyFlag      ;    Push  PropertyFlag
PUSH      DefaultValue      ;    Push  DefaultValue
PUSH      ValidationData    ;    Push  ValidationData
PUSH      ValidationFunc    ;    Push  ValidationFunc
 
CALL      VDHRegisterProperty          ;  Call  the  function </pre>
 
 
 
 
=== VDHRegisterProperty Parameter - PropertyName ===
 
'''PropertyName'''(DD) Pointer to an ASCIIZ string containing the property name. Maximum length is 40 characters.
 
 
 
 
 
=== VDHRegisterProperty Parameter - Reserved ===
 
'''Reserved'''(DD) Must be set to 0 (zero).
 
 
 
 
 
=== VDHRegisterProperty Parameter - Reserved ===
 
'''Reserved'''(DD) Must be set to 0 (zero).
 
 
 
 
 
=== VDHRegisterProperty Parameter - PropertyType ===
 
'''PropertyType'''(DW) Property type.
 
Values are:
 
VDMP_BOOL 0-Boolean <br />VDMP_INT 1-Integer. DD size, but only DW is valid <br />VDMP_ENUM 2-Enumeration <br />VDMP_STRING 3-ASCIIZ string <br />VDMP_MLSTR 4-Multi-line string, separated by linefeed (0AH)
 
 
 
 
 
=== VDHRegisterProperty Parameter - PropertyOrdinal ===
 
'''PropertyOrdinal'''(DW) Property ordinal.
 
Values are:
 
VDMP_ORD_OTHER 0-Custom virtual device driver property <br />VDMP_ORD_KERNEL 1-ASCIIZ path of DOS kernel <br />VDMP_ORD_SHELL 2-ASCIIZ path of DOS_SHELL <br />VDMP_ORD_RMSIZE 3-Integer size of DOS box (128KB-640KB) <br />VDMP_ORD_FCB 4-Integer total FCBs <br />VDMP_ORD_FCB2 5-Integer FCBs immune to close LRUing <br />VDMP_ORD_BREAK 6-Boolean Break flag <br />VDMP_ORD_DOSDD 7-Multi-line string DOS_DEVICE <br />VDMP_ORD_VMBOOT 8-ASCIIZ string virtual machine boot drives <br />VDMP_ORD_VERSION 10-Multi-line string fake version entries <br />VDMP_ORD_DOS_UMB 11-Boolean flag. DOS_UMB <br />VDMP_ORD_DOS_HIGH 12-Boolean flag. DOS_HIGH <br />VDMP_ORD_LASTDRIVE 13-ASCIIZ DOS_LASTDRIVE <br />VDMP_ORD_FILES 14-Integer total FILES
 
 
 
 
 
=== VDHRegisterProperty Parameter - PropertyFlag ===
 
'''PropertyFlag'''(DD) Property flag.
 
Possible value:
 
VDMP_CREATE Property can be specified only at DOS session creation. Any change to the property after DOS session creation is ignored.
 
 
 
 
 
=== VDHRegisterProperty Parameter - DefaultValue ===
 
'''DefaultValue'''(DD) Default value of the property.
 
The format of this field depends on the value of PropertyType:
 
VDMP_BOOL DefaultValue is interpreted as a BOOL (Boolean) value. <br />VDMP_INT DefaultValue is interpreted as a DD value. Only the low half is used (the high half is ignored) so this is more similar to a DW than a DD. <br />VDMP_ENUM DefaultValue is interpreted as a pointer to an ASCIIZ string. <br />VDMP_STRING DefaultValue is interpreted as a pointer to an ASCIIZ string. <br />VDMP_MLSTR DefaultValue is interpreted as a pointer to an ASCIIZ string.
 
 
 
 
 
=== VDHRegisterProperty Parameter - ValidationData ===
 
'''ValidationData'''(DD) Validation data.
 
The value of this field depends on the value of PropertyType.
 
VDMP_BOOL ValidationData is NULL. The user is expected to validate Booleans .
 
VDMP_INT ValidationData is a pointer to a VPBOUND structure:
 
VPBOUND Limits for VDMP_INT properties. Note that maximum '''&gt;'''minimum must hold, the range of maximum to minimum must be a multiple of step, and step= 1 implies that all values between minimum and maximum are valid:
 
<pre class="western">VPBOUND_s STRUC
    min    DW  ?  ; minimum allowed value
    max    DW  ?  ; maximum allowed value
    step  DW  ?  ; increment between values
VPBOUND_s ENDS</pre>
VDMP_ENUM ValidationData is a pointer to a set of ASCIIZ strings terminated by a zero byte, which is the allowed set of responses. The Shell uses this to construct a list or combination box for the user to pick from. Empty (&quot;\ 0&quot;) strings are not allowed.
 
VDMP_STRING ValidationData is a DD that is the maximum allowed string length (including the NULL terminator).
 
VDMP_MLSTR ValidationData is a DD that is the maximum allowed string length (including the NULL terminator).
 
 
 
 
 
=== VDHRegisterProperty Parameter - ValidationFunc ===
 
'''ValidationFunc'''(DD) Function that validates and accepts changes to this property for a running DOS session. Ignored if VDMP_CREATE is specified in conjunction with VDMP_BOOL, VDMP_INT, or VDMP_ENUM.
 
The interface for the ValidationFunc is defined as follows:
 
<pre class="western">VDHPROP_VALIDATE  EQU  0x00000000L
VDHPROP_SET      EQU  0x00000001L
 
ValidationFunc  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - op (DD)
;          [ESP + 12] - hvdm (DD)
;          [ESP +  8] - cb (DD)
;          [ESP +  4] - pch (DD)</pre>
PFNVDHRP is a pointer to a property function of the virtual device driver that performs property setting and validation. This routine is required for any property that does not specify VDMP_CREATE. Set operations can be requested any time after a DOS session is created. The validation operation can be requested at any time, even before a DOS session is created. Validation is requested only for VDMP_STRING and VDMP_MLSTR types because all other types can be validated using the information supplied by VDHRegisterProperty.
 
<pre class="western">Parameter      Data Type      Description
_________      _________      ___________
 
op              DD              Operation to perform.  See the following
                                parameter.
 
hvdm            DD              Handle of DOS session.  Undefined if op =
                                VDHPROP_VALIDATE.
 
cb              DD              Count of bytes pointed by pch.  See the
                                following parameter.
 
pch            DD              Pointer to the value set or validate. See the
                                following parameter.</pre>
op Operation to perform (enumeration):
 
VDHPROP_VALIDATE Validate property for any process. Only called for VDMP_ STRING and VDMP_MLSTR properties. <br />VDHPROP_SET Set an already validated property for specified hvdm. The return code is ignored.
 
cb Count of bytes pointed to by pch. Value depends upon PropertyType:
 
VDMPROP_BOOL Undefined <br />VDMPROP_INT Undefined <br />VDMPROP_ENUM Length of ASCIIZ string including NULL terminator <br />VDMPROP_STRING Length of ASCIIZ string including NULL terminator <br />VDMPROP_MLSTR Length of ASCIIZ string including NULL terminator
 
pch Value to set/validate. The format depends on the property type:
 
VDMPROP_BOOL pch is interpreted as a BOOL (Boolean). Value 0 is FALSE; a nonzero value is TRUE.
 
VDMPROP_INT pch is interpreted as a DD, and is guaranteed to meet the registered bounds.
 
VDMPROP_ENUM pch points to an ASCIIZ string, and is guaranteed to be one of the registered enumeration strings.
 
VDMPROP_STRING pch points to an ASCIIZ string, and is guaranteed to be equal to or less than the registered maximum string length.
 
VDMPROP_MLSTR pch points to an ASCIIZ string. Multiple lines are separated by a line feed (0x0A). It is guaranteed to be less than or equal to the registered maximum string length.
 
 
 
 
 
=== VDHRegisterProperty Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0. ''VDHGetError''should be called to determine the nature of the problem. A system halt occurs if:
 
*Any of the pointers (PropertyName, HelpFile, ValidationData, or ValidationFunc) are invalid <br />*PropertyFlag or PropertyType are invalid <br />*A VPBOUND structure has invalid contents <br />*The maximum string length for a VDMP_STRING is less than the length of the default string value
 
 
 
 
 
=== VDHRegisterProperty - Parameters ===
 
'''PropertyName'''(DD) Pointer to an ASCIIZ string containing the property name. Maximum length is 40 characters.
 
'''Reserved'''(DD) Must be set to 0 (zero).
 
'''Reserved'''(DD) Must be set to 0 (zero).
 
'''PropertyType'''(DW) Property type.
 
Values are:
 
VDMP_BOOL 0-Boolean <br />VDMP_INT 1-Integer. DD size, but only DW is valid <br />VDMP_ENUM 2-Enumeration <br />VDMP_STRING 3-ASCIIZ string <br />VDMP_MLSTR 4-Multi-line string, separated by linefeed (0AH)
 
'''PropertyOrdinal'''(DW) Property ordinal.
 
Values are:
 
VDMP_ORD_OTHER 0-Custom virtual device driver property <br />VDMP_ORD_KERNEL 1-ASCIIZ path of DOS kernel <br />VDMP_ORD_SHELL 2-ASCIIZ path of DOS_SHELL <br />VDMP_ORD_RMSIZE 3-Integer size of DOS box (128KB-640KB) <br />VDMP_ORD_FCB 4-Integer total FCBs <br />VDMP_ORD_FCB2 5-Integer FCBs immune to close LRUing <br />VDMP_ORD_BREAK 6-Boolean Break flag <br />VDMP_ORD_DOSDD 7-Multi-line string DOS_DEVICE <br />VDMP_ORD_VMBOOT 8-ASCIIZ string virtual machine boot drives <br />VDMP_ORD_VERSION 10-Multi-line string fake version entries <br />VDMP_ORD_DOS_UMB 11-Boolean flag. DOS_UMB <br />VDMP_ORD_DOS_HIGH 12-Boolean flag. DOS_HIGH <br />VDMP_ORD_LASTDRIVE 13-ASCIIZ DOS_LASTDRIVE <br />VDMP_ORD_FILES 14-Integer total FILES
 
'''PropertyFlag'''(DD) Property flag.
 
Possible value:
 
VDMP_CREATE Property can be specified only at DOS session creation. Any change to the property after DOS session creation is ignored.
 
'''DefaultValue'''(DD) Default value of the property.
 
The format of this field depends on the value of PropertyType:
 
VDMP_BOOL DefaultValue is interpreted as a BOOL (Boolean) value. <br />VDMP_INT DefaultValue is interpreted as a DD value. Only the low half is used (the high half is ignored) so this is more similar to a DW than a DD. <br />VDMP_ENUM DefaultValue is interpreted as a pointer to an ASCIIZ string. <br />VDMP_STRING DefaultValue is interpreted as a pointer to an ASCIIZ string. <br />VDMP_MLSTR DefaultValue is interpreted as a pointer to an ASCIIZ string.
 
'''ValidationData'''(DD) Validation data.
 
The value of this field depends on the value of PropertyType.
 
VDMP_BOOL ValidationData is NULL. The user is expected to validate Booleans .
 
VDMP_INT ValidationData is a pointer to a VPBOUND structure:
 
VPBOUND Limits for VDMP_INT properties. Note that maximum '''&gt;'''minimum must hold, the range of maximum to minimum must be a multiple of step, and step= 1 implies that all values between minimum and maximum are valid:
 
<pre class="western">VPBOUND_s STRUC
    min    DW  ?  ; minimum allowed value
    max    DW  ?  ; maximum allowed value
    step  DW  ?  ; increment between values
VPBOUND_s ENDS</pre>
VDMP_ENUM ValidationData is a pointer to a set of ASCIIZ strings terminated by a zero byte, which is the allowed set of responses. The Shell uses this to construct a list or combination box for the user to pick from. Empty (&quot;\ 0&quot;) strings are not allowed.
 
VDMP_STRING ValidationData is a DD that is the maximum allowed string length (including the NULL terminator).
 
VDMP_MLSTR ValidationData is a DD that is the maximum allowed string length (including the NULL terminator).
 
'''ValidationFunc'''(DD) Function that validates and accepts changes to this property for a running DOS session. Ignored if VDMP_CREATE is specified in conjunction with VDMP_BOOL, VDMP_INT, or VDMP_ENUM.
 
The interface for the ValidationFunc is defined as follows:
 
<pre class="western">VDHPROP_VALIDATE  EQU  0x00000000L
VDHPROP_SET      EQU  0x00000001L
 
ValidationFunc  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - op (DD)
;          [ESP + 12] - hvdm (DD)
;          [ESP +  8] - cb (DD)
;          [ESP +  4] - pch (DD)</pre>
PFNVDHRP is a pointer to a property function of the virtual device driver that performs property setting and validation. This routine is required for any property that does not specify VDMP_CREATE. Set operations can be requested any time after a DOS session is created. The validation operation can be requested at any time, even before a DOS session is created. Validation is requested only for VDMP_STRING and VDMP_ MLSTR types because all other types can be validated using the information supplied by VDHRegisterProperty.
 
<pre class="western">Parameter      Data Type      Description
_________      _________      ___________
 
op              DD              Operation to perform.  See the following
                                parameter.
 
hvdm            DD              Handle of DOS session.  Undefined if op =
                                VDHPROP_VALIDATE.
 
cb              DD              Count of bytes pointed by pch.  See the
                                following parameter.
 
pch            DD              Pointer to the value set or validate. See the
                                following parameter.</pre>
op Operation to perform (enumeration):
 
VDHPROP_VALIDATE Validate property for any process. Only called for VDMP_ STRING and VDMP_MLSTR properties. <br />VDHPROP_SET Set an already validated property for specified hvdm. The return code is ignored.
 
cb Count of bytes pointed to by pch. Value depends upon PropertyType:
 
VDMPROP_BOOL Undefined <br />VDMPROP_INT Undefined <br />VDMPROP_ENUM Length of ASCIIZ string including NULL terminator <br />VDMPROP_STRING Length of ASCIIZ string including NULL terminator <br />VDMPROP_MLSTR Length of ASCIIZ string including NULL terminator
 
pch Value to set/validate. The format depends on the property type:
 
VDMPROP_BOOL pch is interpreted as a BOOL (Boolean). Value 0 is FALSE; a nonzero value is TRUE.
 
VDMPROP_INT pch is interpreted as a DD, and is guaranteed to meet the registered bounds.
 
VDMPROP_ENUM pch points to an ASCIIZ string, and is guaranteed to be one of the registered enumeration strings.
 
VDMPROP_STRING pch points to an ASCIIZ string, and is guaranteed to be equal to or less than the registered maximum string length.
 
VDMPROP_MLSTR pch points to an ASCIIZ string. Multiple lines are separated by a line feed (0x0A). It is guaranteed to be less than or equal to the registered maximum string length.
 
 
 
 
 
=== VDHRegisterProperty - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: VDHQueryProperty is used to obtain the value of a virtual device driver property for a particular DOS session.
 
 
 
 
 
=== VDHRegisterProperty - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRegisterVDD ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  registers  virtual  device  driver  entry  points  for  use  by  other  virtual  device  drivers
( through  VDHOpenVDD  and  VDHRequestVDD ) ,
and  by  OS / 2  applications
( through  DosOpenVDD  and  DosRequestVDD ) .
* /
 
include  mvdm . inc
 
EXTERN    VDHRegisterVDD : NEAR
VDDName      DD  ?      ;    Pointer  to  the  name  of  the  virtual  device  driver
DosReqFcn    DD  ?      ;    Function  for  use  by  DosRequestVDD
VDDReqFcn    DD  ?      ;    Function  for  use  by  VDHRequestVDD
 
PUSH      VDDName      ;    Push  VDDName
PUSH      DosReqFcn    ;    Push  DosReqFcn
PUSH      VDDReqFcn    ;    Push  VDDReqFcn
 
CALL      VDHRegisterVDD    ;  Call  the  function </pre>
 
 
 
 
=== VDHRegisterVDD - Format ===
 
 
 
<pre class="western">/*
 
This  function  registers  virtual  device  driver  entry  points  for  use  by  other  virtual  device  drivers
( through  VDHOpenVDD  and  VDHRequestVDD ) ,
and  by  OS / 2  applications
( through  DosOpenVDD  and  DosRequestVDD ) .
* /
 
include  mvdm . inc
 
EXTERN    VDHRegisterVDD : NEAR
VDDName      DD  ?      ;    Pointer  to  the  name  of  the  virtual  device  driver
DosReqFcn    DD  ?      ;    Function  for  use  by  DosRequestVDD
VDDReqFcn    DD  ?      ;    Function  for  use  by  VDHRequestVDD
 
PUSH      VDDName      ;    Push  VDDName
PUSH      DosReqFcn    ;    Push  DosReqFcn
PUSH      VDDReqFcn    ;    Push  VDDReqFcn
 
CALL      VDHRegisterVDD    ;  Call  the  function </pre>
 
 
 
 
=== VDHRegisterVDD Parameter - VDDName ===
 
'''VDDName'''(DD) Pointer to the name of the virtual device driver. Maximum length is MAXLENXDD.
 
 
 
 
 
=== VDHRegisterVDD Parameter - DosReqFcn ===
 
'''DosReqFcn'''(DD) Function used by ''DosRequestVDD''. NULL, if none.
 
The interface for the ''DosReqFcn''is:
 
<pre class="western">DosReqFcn  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 24] - SGid    (DW) - Screen Group ID
;          [ESP + 20] - ulCmd  (DD) - Command
;          [ESP + 16] - cbIn    (DD) - Input buffer size
;          [ESP + 12] - pReqIn  (DD) - Input packet
;          [ESP +  8] - cbOut  (DD) - Output buffer size
;          [ESP +  4] - pReqOut (DD) - Output packet
;    EXIT  VDDREQ_PASS  - DOS session manager calls the next routine
;                          registered under same name.
;          Non-zero    - Return failure (For APIs, 0 is success)
;          0            - Return the caller success</pre>
 
 
 
 
 
 
=== VDHRegisterVDD Parameter - VDDReqFcn ===
 
'''VDDReqFcn'''(DD) Function used by ''VDHRequestVDD''. NULL, if none.
 
The interface for the ''VDDReqFcn''is:
 
<pre class="western">VDDReqFcn  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - hvdm (DD)    - DOS session handle
;          [ESP + 12] - ulCmd (DD)  - Command
;          [ESP +  8] - pReqIn (DD)  - Input packet
;          [ESP +  4] - pReqOut (DD) - Output packe
;    EXIT  VDDREQ_PASS  - DOS session manager calls the next routine
;                          registered under same name.
;          Non-zero    - Return success (For Virtual DevHlp services, 1 is success)
;          0            - Return the caller failure</pre>
 
 
 
 
 
 
=== VDHRegisterVDD Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0. If this function is called with invalid parameters or in an incorrect context, a system halt occurs.
 
 
 
 
 
=== VDHRegisterVDD - Parameters ===
 
'''VDDName'''(DD) Pointer to the name of the virtual device driver. Maximum length is MAXLENXDD.
 
'''DosReqFcn'''(DD) Function used by ''DosRequestVDD''. NULL, if none.
 
The interface for the ''DosReqFcn''is:
 
<pre class="western">DosReqFcn  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 24] - SGid    (DW) - Screen Group ID
;          [ESP + 20] - ulCmd  (DD) - Command
;          [ESP + 16] - cbIn    (DD) - Input buffer size
;          [ESP + 12] - pReqIn  (DD) - Input packet
;          [ESP +  8] - cbOut  (DD) - Output buffer size
;          [ESP +  4] - pReqOut (DD) - Output packet
;    EXIT  VDDREQ_PASS  - DOS session manager calls the next routine
;                          registered under same name.
;          Non-zero    - Return failure (For APIs, 0 is success)
;          0            - Return the caller success</pre>
 
 
'''VDDReqFcn'''(DD) Function used by ''VDHRequestVDD''. NULL, if none.
 
The interface for the ''VDDReqFcn''is:
 
<pre class="western">VDDReqFcn  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - hvdm (DD)    - DOS session handle
;          [ESP + 12] - ulCmd (DD)  - Command
;          [ESP +  8] - pReqIn (DD)  - Input packet
;          [ESP +  4] - pReqOut (DD) - Output packe
;    EXIT  VDDREQ_PASS  - DOS session manager calls the next routine
;                          registered under same name.
;          Non-zero    - Return success (For Virtual DevHlp services, 1 is success)
;          0            - Return the caller failure</pre>
 
 
 
 
 
 
=== VDHRegisterVDD - Purpose ===
 
Context Issues: This function can be called only in the initialization context.
 
DOS Session Terminations: The virtual device driver must communicate with any virtual device driver or OS/2 clients, to ensure that the resources for the terminating DOS session are freed.
 
Notes: If a virtual device driver fails in its INIT routine after registering (through ''VDHRegisterVDD''), the deregistration is done automatically at the time the virtual device driver is unloaded. Because two or more virtual device drivers can register the same name (''VDDName''), the DOS Session Manager calls each virtual device driver's routine in turn, until one of them returns a nonzero value.
 
Note that the order of the calling sequence is not consistent.
 
 
 
 
 
=== VDHRegisterVDD - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHReleaseCodePageFont ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  releases  a  code  page  font  loaded  with
VDHGetCodePageFont .
If  system  memory  was  allocated  to  hold  the
specified  font ,  this  call  will  free  that  memory .
* /
 
include  mvdm . inc
 
EXTERN    VDHReleaseCodePageFont : NEAR
FontPtr    DD  ?      ;    Pointer  returned  by  VDHGetCodePageFont
 
PUSH      FontPtr    ;    Push  FontPtr
 
CALL      VDHReleaseCodePageFont ;  Call  the  function </pre>
 
 
 
 
=== VDHReleaseCodePageFont - Format ===
 
 
 
<pre class="western">/*
 
This  function  releases  a  code  page  font  loaded  with
VDHGetCodePageFont .
If  system  memory  was  allocated  to  hold  the
specified  font ,  this  call  will  free  that  memory .
* /
 
include  mvdm . inc
 
EXTERN    VDHReleaseCodePageFont : NEAR
FontPtr    DD  ?      ;    Pointer  returned  by  VDHGetCodePageFont
 
PUSH      FontPtr    ;    Push  FontPtr
 
CALL      VDHReleaseCodePageFont ;  Call  the  function </pre>
 
 
 
 
=== VDHReleaseCodePageFont Parameter - FontPtr ===
 
'''FontPtr'''(DD) Pointer returned in ''FontAddress''by ''VDHGetCodePageFont''.
 
 
 
 
 
=== VDHReleaseCodePageFont Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''FontPtr''is not valid, a system halt occurs.
 
 
 
 
 
=== VDHReleaseCodePageFont - Parameters ===
 
'''FontPtr'''(DD) Pointer returned in ''FontAddress''by ''VDHGetCodePageFont''.
 
 
 
 
 
=== VDHReleaseCodePageFont - Purpose ===
 
Context Issues: This function can be called only in the DOS session task context.
 
DOS Session Terminations: The virtual device driver must call this function for any code page fonts loaded for this DOS session.
 
 
 
 
 
=== VDHReleaseCodePageFont - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHReleaseMutexSem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  releases  the  ownership  of  a  mutex  semaphore .
If  the
request  count  becomes  0  ( zero ) ,  the  highest  priority
semaphore  is  awakened .
* /
 
include  mvdm . inc
 
EXTERN    VDHReleaseMutexSem : NEAR
MutexSemHandle    DD  ?      ;    Handle  of  the  semaphore  to  be  released
 
PUSH      MutexSemHandle    ;    Push  MutexSemHandle
 
CALL      VDHReleaseMutexSem        ;  Call  the  function </pre>
 
 
 
 
=== VDHReleaseMutexSem - Format ===
 
 
 
<pre class="western">/*
 
This  function  releases  the  ownership  of  a  mutex  semaphore .
If  the
request  count  becomes  0  ( zero ) ,  the  highest  priority
semaphore  is  awakened .
* /
 
include  mvdm . inc
 
EXTERN    VDHReleaseMutexSem : NEAR
MutexSemHandle    DD  ?      ;    Handle  of  the  semaphore  to  be  released
 
PUSH      MutexSemHandle    ;    Push  MutexSemHandle
 
CALL      VDHReleaseMutexSem        ;  Call  the  function </pre>
 
 
 
 
=== VDHReleaseMutexSem Parameter - MutexSemHandle ===
 
'''MutexSemHandle'''(DD) Handle of the semaphore to be released.
 
 
 
 
 
=== VDHReleaseMutexSem Return Value - rc ===
 
Success If the function is successful, it returns nothing and the semaphore in ''MutexSemHandle''is released.
 
Failure If the virtual device driver that called ''VDHReleaseMutexSem''is not the owner of the semaphore to be released, or if ''MutexSemHandle''invalid, a system halt occurs.
 
 
 
 
 
=== VDHReleaseMutexSem - Parameters ===
 
'''MutexSemHandle'''(DD) Handle of the semaphore to be released.
 
 
 
 
 
=== VDHReleaseMutexSem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHReleaseMutexSem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRemoveFaultHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  removes  the  page  fault  handler  hook  for  the  specified
DOS  session  page  range .
* /
 
include  mvdm . inc
 
EXTERN    VDHRemoveFaultHook : NEAR
VDMHandle                  DD  ?      ;    DOS  session  handle .    0  =  current  DOS  session
StartingAddress          DD  ?      ;    Starting  linear  address
Pages                      DD  ?      ;    Number  of  pages
PageFaultHandlerFcnPtr    DD  ?      ;    Function  supplied  to  VDHInstallFaultHook
 
PUSH      VDMHandle                  ;    Push  VDMHandle
PUSH      StartingAddress          ;    Push  StartingAddress
PUSH      Pages                      ;    Push  Pages
PUSH      PageFaultHandlerFcnPtr    ;    Push  PageFaultHandlerFcnPtr
 
CALL      VDHRemoveFaultHook                  ;  Call  the  function </pre>
 
 
 
 
=== VDHRemoveFaultHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  removes  the  page  fault  handler  hook  for  the  specified
DOS  session  page  range .
* /
 
include  mvdm . inc
 
EXTERN    VDHRemoveFaultHook : NEAR
VDMHandle                  DD  ?      ;    DOS  session  handle .    0  =  current  DOS  session
StartingAddress          DD  ?      ;    Starting  linear  address
Pages                      DD  ?      ;    Number  of  pages
PageFaultHandlerFcnPtr    DD  ?      ;    Function  supplied  to  VDHInstallFaultHook
 
PUSH      VDMHandle                  ;    Push  VDMHandle
PUSH      StartingAddress          ;    Push  StartingAddress
PUSH      Pages                      ;    Push  Pages
PUSH      PageFaultHandlerFcnPtr    ;    Push  PageFaultHandlerFcnPtr
 
CALL      VDHRemoveFaultHook                  ;  Call  the  function </pre>
 
 
 
 
=== VDHRemoveFaultHook Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
 
 
 
 
=== VDHRemoveFaultHook Parameter - StartingAddress ===
 
'''StartingAddress'''(DD) Starting linear address.
 
 
 
 
 
=== VDHRemoveFaultHook Parameter - Pages ===
 
'''Pages'''(DD) Number of pages.
 
 
 
 
 
=== VDHRemoveFaultHook Parameter - PageFaultHandlerFcnPtr ===
 
'''PageFaultHandlerFcnPtr'''(DD) Function supplied to ''VDHInstallFaultHook''. This is used to verify that the calling virtual device driver is the one that installed the fault hook.
 
 
 
 
 
=== VDHRemoveFaultHook Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If any of the input parameters are invalid, a system halt occurs.
 
 
 
 
 
=== VDHRemoveFaultHook - Parameters ===
 
'''VDMHandle'''(DD) DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
'''StartingAddress'''(DD) Starting linear address.
 
'''Pages'''(DD) Number of pages.
 
'''PageFaultHandlerFcnPtr'''(DD) Function supplied to ''VDHInstallFaultHook''. This is used to verify that the calling virtual device driver is the one that installed the fault hook.
 
 
 
 
 
=== VDHRemoveFaultHook - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: Any fault hooks for the terminating DOS session must be released.
 
 
 
 
 
=== VDHRemoveFaultHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRemoveIOHook ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  must  be  called  with
StartingPort  and  NumPorts
to  remove  the  I / O  hooks  for  the  specified  I / O  ports .
Port  hooks  cannot  be  removed  for  a  subset  of  the  range  of  ports
hooked  by  VDHInstallIOHook .
* /
 
include  mvdm . inc
 
EXTERN    VDHRemoveIOHook : NEAR
Reserved        DD  ?      ;    Reserved .    Must  be  set  to  0  ( zero ) .
StartingPort    DD  ?      ;    Starting  port  number
NumPorts        DD  ?      ;    Number  of  ports  in  the  range
IOPortHook      DD  ?      ;    Pointer  to  installed  I / O  hook  entry
 
PUSH      Reserved        ;    Push  Reserved
PUSH      StartingPort    ;    Push  StartingPort
PUSH      NumPorts        ;    Push  NumPorts
PUSH      IOPortHook      ;    Push  IOPortHook
 
CALL      VDHRemoveIOHook      ;  Call  the  function </pre>
 
 
 
 
=== VDHRemoveIOHook - Format ===
 
 
 
<pre class="western">/*
 
This  function  must  be  called  with
StartingPort  and  NumPorts
to  remove  the  I / O  hooks  for  the  specified  I / O  ports .
Port  hooks  cannot  be  removed  for  a  subset  of  the  range  of  ports
hooked  by  VDHInstallIOHook .
* /
 
include  mvdm . inc
 
EXTERN    VDHRemoveIOHook : NEAR
Reserved        DD  ?      ;    Reserved .    Must  be  set  to  0  ( zero ) .
StartingPort    DD  ?      ;    Starting  port  number
NumPorts        DD  ?      ;    Number  of  ports  in  the  range
IOPortHook      DD  ?      ;    Pointer  to  installed  I / O  hook  entry
 
PUSH      Reserved        ;    Push  Reserved
PUSH      StartingPort    ;    Push  StartingPort
PUSH      NumPorts        ;    Push  NumPorts
PUSH      IOPortHook      ;    Push  IOPortHook
 
CALL      VDHRemoveIOHook      ;  Call  the  function </pre>
 
 
 
 
=== VDHRemoveIOHook Parameter - Reserved ===
 
'''Reserved'''(DD) Reserved. Must be set to 0.
 
 
 
 
 
=== VDHRemoveIOHook Parameter - StartingPort ===
 
'''StartingPort'''(DD) Starting port number.
 
 
 
 
 
=== VDHRemoveIOHook Parameter - NumPorts ===
 
'''NumPorts'''(DD) Number of ports in the range.
 
 
 
 
 
=== VDHRemoveIOHook Parameter - IOPortHook ===
 
'''IOPortHook'''(DD) Pointer to installed I/O hook entry. This parameter is used to verify that the calling virtual device driver is the one that installed the I/O hook.
 
 
 
 
 
=== VDHRemoveIOHook Return Value - rc ===
 
Success If the function was successful, it returns nothing.
 
Failure If ''IOPortHookEntry''is invalid or if ''StartingPort''or ''NumPorts''are out of range, a system halt occurs.
 
 
 
 
 
=== VDHRemoveIOHook - Parameters ===
 
'''Reserved'''(DD) Reserved. Must be set to 0.
 
'''StartingPort'''(DD) Starting port number.
 
'''NumPorts'''(DD) Number of ports in the range.
 
'''IOPortHook'''(DD) Pointer to installed I/O hook entry. This parameter is used to verify that the calling virtual device driver is the one that installed the I/O hook.
 
 
 
 
 
=== VDHRemoveIOHook - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function. I/O hooks are automatically removed during DOS session termination.
 
Notes: If the ''IOPortHook''is in instance data, the address passed ''VDHInstallIOHook''must be the same address passed to ''VDHRemoveIOHook''or ''VDHSetIOHookState''.
 
 
 
 
 
=== VDHRemoveIOHook - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHReportPeek ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  reports  DOS  session  polling  activity .
A  counter  of  idle  polling  activity  is  incremented .
If  the  count  exceeds  a  threshold ,
the  current  DOS  session  is  put  to  sleep  for  a  period .
* /
 
include  mvdm . inc
 
EXTERN    VDHReportPeek : NEAR
PeekWeight    DD  ?      ;    Value  to  add  to  the  idle  counter
 
PUSH      PeekWeight    ;    Push  PeekWeight
 
CALL      VDHReportPeek    ;  Call  the  function </pre>
 
 
 
 
=== VDHReportPeek - Format ===
 
 
 
<pre class="western">/*
 
This  function  reports  DOS  session  polling  activity .
A  counter  of  idle  polling  activity  is  incremented .
If  the  count  exceeds  a  threshold ,
the  current  DOS  session  is  put  to  sleep  for  a  period .
* /
 
include  mvdm . inc
 
EXTERN    VDHReportPeek : NEAR
PeekWeight    DD  ?      ;    Value  to  add  to  the  idle  counter
 
PUSH      PeekWeight    ;    Push  PeekWeight
 
CALL      VDHReportPeek    ;  Call  the  function </pre>
 
 
 
 
=== VDHReportPeek Parameter - PeekWeight ===
 
'''PeekWeight'''(DD) Value to add to the idle counter.
 
 
 
 
 
=== VDHReportPeek Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If the current process is not a DOS session, a system halt occurs.
 
 
 
 
 
=== VDHReportPeek - Parameters ===
 
'''PeekWeight'''(DD) Value to add to the idle counter.
 
 
 
 
 
=== VDHReportPeek - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Any virtual device driver that can detect idle polling activity can call this service to report it. If the sum of peek weights exceeds 64KB in a single VDHGSV_MSECSBOOT clock tick (see [[00822.htm|VDHQuerySysValue]]), the DOS session is considered idle. It is the responsibility of the virtual device driver to calibrate its peek weight. This depends on machine speed and the Ring 0 trap overhead time, and therefore cannot be calibrated from measuring peek rate under DOS.
 
Note that testing the time before the count ensures that new tests begin at the first peek in a time slice. This allows use of a very short test period .
 
 
 
 
 
=== VDHReportPeek - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRequestMutexSem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  requests  the  ownership  of  a  mutex  semaphore .
If  the  semaphore  is  owned  and  the  caller  is  not  the  owner ,  the
thread  will  block .
If  the  caller  is  the  owner ,  a  request  count  is  incremented .
Request  calls  can  be  nested .
A  maximum  of
65 , 535
( 64KB )  requests
are  allowed  for  each  semaphore  at  any  one  time .
Exceeding  this  limit  results  in  a  system  halt .
* /
 
include  mvdm . inc
 
EXTERN    VDHRequestMutexSem : NEAR
MutexSemHandle    DD  ?      ;    Mutex  semaphore  handle
Timeout          DD  ?      ;    Timeout  ( in  milliseconds )
 
PUSH      MutexSemHandle    ;    Push  MutexSemHandle
PUSH      Timeout          ;    Push  Timeout
 
CALL      VDHRequestMutexSem        ;  Call  the  function </pre>
 
 
 
 
=== VDHRequestMutexSem - Format ===
 
 
 
<pre class="western">/*
 
This  function  requests  the  ownership  of  a  mutex  semaphore .
If  the  semaphore  is  owned  and  the  caller  is  not  the  owner ,  the
thread  will  block .
If  the  caller  is  the  owner ,  a  request  count  is  incremented .
Request  calls  can  be  nested .
A  maximum  of
65 , 535
( 64KB )  requests
are  allowed  for  each  semaphore  at  any  one  time .
Exceeding  this  limit  results  in  a  system  halt .
* /
 
include  mvdm . inc
 
EXTERN    VDHRequestMutexSem : NEAR
MutexSemHandle    DD  ?      ;    Mutex  semaphore  handle
Timeout          DD  ?      ;    Timeout  ( in  milliseconds )
 
PUSH      MutexSemHandle    ;    Push  MutexSemHandle
PUSH      Timeout          ;    Push  Timeout
 
CALL      VDHRequestMutexSem        ;  Call  the  function </pre>
 
 
 
 
=== VDHRequestMutexSem Parameter - MutexSemHandle ===
 
'''MutexSemHandle'''(DD) Mutex semaphore handle.
 
 
 
 
 
=== VDHRequestMutexSem Parameter - Timeout ===
 
'''Timeout'''(DD) Number of milliseconds to wait before timing out the semaphore .
 
 
 
 
 
=== VDHRequestMutexSem Return Value - rc ===
 
Success If the function is successful, it returns 1.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. An invalid semaphore will result in a system halt. A system halt also occurs if the request count crosses the 64KB limit.
 
 
 
 
 
=== VDHRequestMutexSem - Parameters ===
 
'''MutexSemHandle'''(DD) Mutex semaphore handle.
 
'''Timeout'''(DD) Number of milliseconds to wait before timing out the semaphore .
 
 
 
 
 
=== VDHRequestMutexSem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHRequestMutexSem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHRequestVDD ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  requests  an  operation  of  a  virtual  device  driver .
This  service  is  also  used  for  communication  between  two  or  more
virtual  device  drivers  where  dynamic  linkage  between  them  is  not  appropriate .
* /
 
include  mvdm . inc
 
EXTERN    VDHRequestVDD : NEAR
VDDHandle              DD  ?      ;    Virtual  device  driver  handle
VDMHandle              DD  ?      ;    DOS  session  handle
Command                DD  ?      ;    Command  requested
InputRequestPacket    DD  ?      ;    Pointer  to  the  input  packet
OutputRequestPacket    DD  ?      ;    Pointer  to  the  output  packet
 
PUSH      VDDHandle              ;    Push  VDDHandle
PUSH      VDMHandle              ;    Push  VDMHandle
PUSH      Command                ;    Push  Command
PUSH      InputRequestPacket    ;    Push  InputRequestPacket
PUSH      OutputRequestPacket    ;    Push  OutputRequestPacket
 
CALL      VDHRequestVDD              ;  Call  the  function </pre>
 
 
 
 
=== VDHRequestVDD - Format ===
 
 
 
<pre class="western">/*
 
This  function  requests  an  operation  of  a  virtual  device  driver .
This  service  is  also  used  for  communication  between  two  or  more
virtual  device  drivers  where  dynamic  linkage  between  them  is  not  appropriate .
* /
 
include  mvdm . inc
 
EXTERN    VDHRequestVDD : NEAR
VDDHandle              DD  ?      ;    Virtual  device  driver  handle
VDMHandle              DD  ?      ;    DOS  session  handle
Command                DD  ?      ;    Command  requested
InputRequestPacket    DD  ?      ;    Pointer  to  the  input  packet
OutputRequestPacket    DD  ?      ;    Pointer  to  the  output  packet
 
PUSH      VDDHandle              ;    Push  VDDHandle
PUSH      VDMHandle              ;    Push  VDMHandle
PUSH      Command                ;    Push  Command
PUSH      InputRequestPacket    ;    Push  InputRequestPacket
PUSH      OutputRequestPacket    ;    Push  OutputRequestPacket
 
CALL      VDHRequestVDD              ;  Call  the  function </pre>
 
 
 
 
=== VDHRequestVDD Parameter - VDDHandle ===
 
'''VDDHandle'''(DD) Handle to a virtual device driver.
 
 
 
 
 
=== VDHRequestVDD Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) Handle to a DOS session.
 
 
 
 
 
=== VDHRequestVDD Parameter - Command ===
 
'''Command'''(DD) Command requested.
 
 
 
 
 
=== VDHRequestVDD Parameter - InputRequestPacket ===
 
'''InputRequestPacket'''(DD) Pointer to the input packet.
 
 
 
 
 
=== VDHRequestVDD Parameter - OutputRequestPacket ===
 
'''OutputRequestPacket'''(DD) Pointer to the output packet.
 
 
 
 
 
=== VDHRequestVDD Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''VDDHandle''or ''VDMHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHRequestVDD - Parameters ===
 
'''VDDHandle'''(DD) Handle to a virtual device driver.
 
'''VDMHandle'''(DD) Handle to a DOS session.
 
'''Command'''(DD) Command requested.
 
'''InputRequestPacket'''(DD) Pointer to the input packet.
 
'''OutputRequestPacket'''(DD) Pointer to the output packet.
 
 
 
 
 
=== VDHRequestVDD - Purpose ===
 
Context Issues: This function can be called in the task or the interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Every ''VDHRequestVDD''procedure registered under the virtual device driver name associated with the given handle is called until one returns a nonzero value. No assumption should be made about the order of the calling sequence.
 
The virtual device driver worker routine sets the error with ''VDHSetError''when it returns 0 (zero). If the calling virtual device driver is registered under the same name as the virtual device driver handle, then its entry point is also called. Furthermore, the DOS Session Manager does not prevent any of the called virtual device drivers from issuing another ''VDHRequestVDD''.
 
 
 
 
 
=== VDHRequestVDD - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHReservePages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  reserves  a  range  of  linear  addresses  for  later  use  with
VDHMapPages  or  VDHAllocPages .
A  reserved  area  cannot  contain  a
mixture  of  pages  set  by
VDHMapPages  and  VDHAllocPages ,  but  it  can
be  used  successively  with  either  one .
* /
 
include  mvdm . inc
 
EXTERN    VDHReservePages : NEAR
StartingAddress    DD  ?      ;    Starting  address  of  the  linear  memory  to  reserve
NumPages          DD  ?      ;    Number  of  pages  to  reserve
 
PUSH      StartingAddress    ;    Push  StartingAddress
PUSH      NumPages          ;    Push  NumPages
 
CALL      VDHReservePages          ;  Call  the  function </pre>
 
 
 
 
=== VDHReservePages - Format ===
 
 
 
<pre class="western">/*
 
This  function  reserves  a  range  of  linear  addresses  for  later  use  with
VDHMapPages  or  VDHAllocPages .
A  reserved  area  cannot  contain  a
mixture  of  pages  set  by
VDHMapPages  and  VDHAllocPages ,  but  it  can
be  used  successively  with  either  one .
* /
 
include  mvdm . inc
 
EXTERN    VDHReservePages : NEAR
StartingAddress    DD  ?      ;    Starting  address  of  the  linear  memory  to  reserve
NumPages          DD  ?      ;    Number  of  pages  to  reserve
 
PUSH      StartingAddress    ;    Push  StartingAddress
PUSH      NumPages          ;    Push  NumPages
 
CALL      VDHReservePages          ;  Call  the  function </pre>
 
 
 
 
=== VDHReservePages Parameter - StartingAddress ===
 
'''StartingAddress'''(DD) Starting address of the linear memory to reserve. Must be page aligned and must be less than 110000H (1MB + 64KB).
 
 
 
 
 
=== VDHReservePages Parameter - NumPages ===
 
'''NumPages'''(DD) Number of pages to reserve.
 
 
 
 
 
=== VDHReservePages Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value and the pages are reserved for later access.
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''StartingAddress''or ''NumPages''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHReservePages - Parameters ===
 
'''StartingAddress'''(DD) Starting address of the linear memory to reserve. Must be page aligned and must be less than 110000H (1MB + 64KB).
 
'''NumPages'''(DD) Number of pages to reserve.
 
 
 
 
 
=== VDHReservePages - Purpose ===
 
Context Issues: This function can be called in the initialization and DOS session-task contexts. In the initialization context, the reservation affects only the global linear memory map. In the DOS session-task context, reservations affect only the local linear memory map.
 
DOS Session Terminations: There are no DOS session termination implications for this function. The DOS Session Manager will clean up these reservations when the DOS session terminates.
 
 
 
 
 
=== VDHReservePages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHResetEventSem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  resets  an  event  semaphore .
* /
 
include  mvdm . inc
 
EXTERN    VDHResetEventSem : NEAR
EventSemHandle    DD  ?      ;    Handle  to  the  event  semaphore  to  be  reset
 
PUSH      EventSemHandle    ;    Push  EventSemHandle
 
CALL      VDHResetEventSem        ;  Call  the  function </pre>
 
 
 
 
=== VDHResetEventSem - Format ===
 
 
 
<pre class="western">/*
 
This  function  resets  an  event  semaphore .
* /
 
include  mvdm . inc
 
EXTERN    VDHResetEventSem : NEAR
EventSemHandle    DD  ?      ;    Handle  to  the  event  semaphore  to  be  reset
 
PUSH      EventSemHandle    ;    Push  EventSemHandle
 
CALL      VDHResetEventSem        ;  Call  the  function </pre>
 
 
 
 
=== VDHResetEventSem Parameter - EventSemHandle ===
 
'''EventSemHandle'''(DD) Handle to the event semaphore to be reset.
 
 
 
 
 
=== VDHResetEventSem Return Value - rc ===
 
Success If the function is successful, it returns nothing and the semaphore is reset.
 
Failure Resetting a semaphore that is invalid or is already reset causes a system halt to occur.
 
 
 
 
 
=== VDHResetEventSem - Parameters ===
 
'''EventSemHandle'''(DD) Handle to the event semaphore to be reset.
 
 
 
 
 
=== VDHResetEventSem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHResetEventSem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSeek ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  seeks  to  a  specified  position  within  a  file  previously
opened  by  VDHOpen .
* /
 
include  mvdm . inc
 
EXTERN    VDHSeek : NEAR
FileHandle      DW  ?      ;    Handle  to  the  file
NewOffset      DD  ?      ;    Offset  of  the  new  file - pointer  position
MoveTypeFlag    DD  ?      ;    Type  of  move  ( absolute ,  relative )
 
PUSH      FileHandle      ;    Push  FileHandle
PUSH      NewOffset      ;    Push  NewOffset
PUSH      MoveTypeFlag    ;    Push  MoveTypeFlag
 
CALL      VDHSeek      ;  Call  the  function </pre>
 
 
 
 
=== VDHSeek - Format ===
 
 
 
<pre class="western">/*
 
This  function  seeks  to  a  specified  position  within  a  file  previously
opened  by  VDHOpen .
* /
 
include  mvdm . inc
 
EXTERN    VDHSeek : NEAR
FileHandle      DW  ?      ;    Handle  to  the  file
NewOffset      DD  ?      ;    Offset  of  the  new  file - pointer  position
MoveTypeFlag    DD  ?      ;    Type  of  move  ( absolute ,  relative )
 
PUSH      FileHandle      ;    Push  FileHandle
PUSH      NewOffset      ;    Push  NewOffset
PUSH      MoveTypeFlag    ;    Push  MoveTypeFlag
 
CALL      VDHSeek      ;  Call  the  function </pre>
 
 
 
 
=== VDHSeek Parameter - FileHandle ===
 
'''FileHandle'''(DW) Handle to the file.
 
 
 
 
 
=== VDHSeek Parameter - NewOffset ===
 
'''NewOffset'''(DD) Offset to the new file-pointer position. Depending on the value of ''MoveTypeFlag'', this can be the offset from the beginning of the file, the ending of the file, or the current position of the file-pointer.
 
 
 
 
 
=== VDHSeek Parameter - MoveTypeFlag ===
 
'''MoveTypeFlag'''(DD) Indicates what type of move is being done.
 
Possible values are:
 
VDHSK_ABSOLUTE Move file-pointer to a location relative to the beginning of the file <br />VDHSK_CURRENT_POSITION Move file-pointer relative to its current position <br />VDHSK_END_OF_FILE Move file-pointer to a location relative to the end of the file
 
 
 
 
 
=== VDHSeek Return Value - rc ===
 
Success If the function is successful, it returns the new current absolute position of the file-pointer within the file.
 
Failure If the function fails, it returns 0FFFFFFFFH. ''VDHGetError''should be called to determine the nature of the problem. If ''FileHandle''is invalid, or if this function is not called in the DOS session-task context, a system halt occurs.
 
 
 
 
 
=== VDHSeek - Parameters ===
 
'''FileHandle'''(DW) Handle to the file.
 
'''NewOffset'''(DD) Offset to the new file-pointer position. Depending on the value of ''MoveTypeFlag'', this can be the offset from the beginning of the file, the ending of the file, or the current position of the file-pointer.
 
'''MoveTypeFlag'''(DD) Indicates what type of move is being done.
 
Possible values are:
 
VDHSK_ABSOLUTE Move file-pointer to a location relative to the beginning of the file <br />VDHSK_CURRENT_POSITION Move file-pointer relative to its current position <br />VDHSK_END_OF_FILE Move file-pointer to a location relative to the end of the file
 
 
 
 
 
=== VDHSeek - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHSeek - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSendVEOI ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  sends  a  virtual  End - Of - Interrupt  ( EOI )  signal  to  the
Virtual  Programmable  Interrupt  Controller  ( VPIC ) ,  and  clears  the
in - service  state  of  the  IRQ  for  the  calling  device .
The  EOI  handler  for  the  IRQ  is  called ,  if  one  exists .
* /
 
include  mvdm . inc
 
EXTERN    VDHSendVEOI : NEAR
IRQHandle    DD  ?      ;    IRQ  handle
 
PUSH      IRQHandle    ;    Push  IRQHandle
 
CALL      VDHSendVEOI    ;  Call  the  function </pre>
 
 
 
 
=== VDHSendVEOI - Format ===
 
 
 
<pre class="western">/*
 
This  function  sends  a  virtual  End - Of - Interrupt  ( EOI )  signal  to  the
Virtual  Programmable  Interrupt  Controller  ( VPIC ) ,  and  clears  the
in - service  state  of  the  IRQ  for  the  calling  device .
The  EOI  handler  for  the  IRQ  is  called ,  if  one  exists .
* /
 
include  mvdm . inc
 
EXTERN    VDHSendVEOI : NEAR
IRQHandle    DD  ?      ;    IRQ  handle
 
PUSH      IRQHandle    ;    Push  IRQHandle
 
CALL      VDHSendVEOI    ;  Call  the  function </pre>
 
 
 
 
=== VDHSendVEOI Parameter - IRQHandle ===
 
'''IRQHandle'''(DD) IRQ handle.
 
 
 
 
 
=== VDHSendVEOI Return Value - rc ===
 
Success If the function was successful, it returns nothing.
 
Failure If ''IRQHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHSendVEOI - Parameters ===
 
'''IRQHandle'''(DD) IRQ handle.
 
 
 
 
 
=== VDHSendVEOI - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHSendVEOI - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetDosDevice ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  links  a  DOS  device  driver  into  the  chain  of  DOS  device
drivers  for  a  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetDosDevice : NEAR
vpDosDD    DD  ?      ;    V86  FAR  address  of  the  DOS  device  driver  header
 
PUSH      vpDosDD    ;    Push  vpDosDD
 
CALL      VDHSetDosDevice ;  Call  the  function </pre>
 
 
 
 
=== VDHSetDosDevice - Format ===
 
 
 
<pre class="western">/*
 
This  function  links  a  DOS  device  driver  into  the  chain  of  DOS  device
drivers  for  a  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetDosDevice : NEAR
vpDosDD    DD  ?      ;    V86  FAR  address  of  the  DOS  device  driver  header
 
PUSH      vpDosDD    ;    Push  vpDosDD
 
CALL      VDHSetDosDevice ;  Call  the  function </pre>
 
 
 
 
=== VDHSetDosDevice Parameter - vpDosDD ===
 
'''vpDosDD'''(DD) V86 FAR address of the DOS device driver header. This header ( and any headers chained to it) are entered into the DOS device driver list for this DOS session.
 
 
 
 
 
=== VDHSetDosDevice Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHSetDosDevice - Parameters ===
 
'''vpDosDD'''(DD) V86 FAR address of the DOS device driver header. This header ( and any headers chained to it) are entered into the DOS device driver list for this DOS session.
 
 
 
 
 
=== VDHSetDosDevice - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context (DOS session creation only).
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHSetDosDevice - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetError ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  sets  the  error  code  for  return  by
VDHGetError .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetError : NEAR
ErrorCode    DD  ?      ;    Error  code  to  set
 
PUSH      ErrorCode    ;    Push  ErrorCode
 
CALL      VDHSetError    ;  Call  the  function </pre>
 
 
 
 
=== VDHSetError - Format ===
 
 
 
<pre class="western">/*
 
This  function  sets  the  error  code  for  return  by
VDHGetError .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetError : NEAR
ErrorCode    DD  ?      ;    Error  code  to  set
 
PUSH      ErrorCode    ;    Push  ErrorCode
 
CALL      VDHSetError    ;  Call  the  function </pre>
 
 
 
 
=== VDHSetError Parameter - ErrorCode ===
 
'''ErrorCode'''(DD) Error code to set for ''VDHGetError''.
 
 
 
 
 
=== VDHSetError Return Value - rc ===
 
None.
 
 
 
 
 
=== VDHSetError - Parameters ===
 
'''ErrorCode'''(DD) Error code to set for ''VDHGetError''.
 
 
 
 
 
=== VDHSetError - Purpose ===
 
Context Issues: This function can be called in any context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This function is intended for use by any virtual device driver that offers dynamic link services to other virtual device drivers. Most of the base errors are defined in BSEERR.INC. Where possible, these definitions are used when returning errors.
 
 
 
 
 
=== VDHSetError - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetFlags ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  sets  the  DOS  session ' s  Flags  Register  to  specified
values .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetFlags : NEAR
FlagValue    DD  ?      ;    DOS  session  flag  value
 
PUSH      FlagValue    ;    Push  FlagValue
 
CALL      VDHSetFlags    ;  Call  the  function </pre>
 
 
 
 
=== VDHSetFlags - Format ===
 
 
 
<pre class="western">/*
 
This  function  sets  the  DOS  session ' s  Flags  Register  to  specified
values .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetFlags : NEAR
FlagValue    DD  ?      ;    DOS  session  flag  value
 
PUSH      FlagValue    ;    Push  FlagValue
 
CALL      VDHSetFlags    ;  Call  the  function </pre>
 
 
 
 
=== VDHSetFlags Parameter - FlagValue ===
 
'''FlagValue'''(DD) DOS session flag value that sets the flag register of the DOS session.
 
 
 
 
 
=== VDHSetFlags Return Value - ===
 
None.
 
 
 
 
 
=== VDHSetFlags - Parameters ===
 
'''FlagValue'''(DD) DOS session flag value that sets the flag register of the DOS session.
 
 
 
 
 
=== VDHSetFlags - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Virtual device drivers must use this interface instead of the client register frame pointer to change the DOS session's flags. Changes to the interrupt flag and the I/O Privilege Level (IOPL) field must be under the control of 8086 emulation so that ''VDHArmSTIHook''works correctly.
 
Nested Task (NT) and Resume Flag (RF) flags are cleared, the virtual 8086 Mode (VM) flag is set, and the IOPL field is left unchanged. This function does not take effect until the operating system returns to V86 mode.
 
 
 
 
 
=== VDHSetFlags - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetIOHookState ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  to  enable  and  disable  I / O  port  trapping
for  a  range  of  ports .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetIOHookState : NEAR
Reserved        DD  ?      ;    Reserved .    Must  be  set  to  0
StartingPort    DD  ?      ;    Starting  port  number
NumPorts        DD  ?      ;    Number  of  ports  in  the  range
IOPortHook      DD  ?      ;    Pointer  used  to  install  I / O  hooks
EnableFlag      DD  ?      ;    FLag  for  setting  I / O  hooks
 
PUSH      Reserved        ;    Push  Reserved
PUSH      StartingPort    ;    Push  StartingPort
PUSH      NumPorts        ;    Push  NumPorts
PUSH      IOPortHook      ;    Push  IOPortHook
PUSH      EnableFlag      ;    Push  EnableFlag
 
CALL      VDHSetIOHookState      ;  Call  the  function </pre>
 
 
 
 
=== VDHSetIOHookState - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  to  enable  and  disable  I / O  port  trapping
for  a  range  of  ports .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetIOHookState : NEAR
Reserved        DD  ?      ;    Reserved .    Must  be  set  to  0
StartingPort    DD  ?      ;    Starting  port  number
NumPorts        DD  ?      ;    Number  of  ports  in  the  range
IOPortHook      DD  ?      ;    Pointer  used  to  install  I / O  hooks
EnableFlag      DD  ?      ;    FLag  for  setting  I / O  hooks
 
PUSH      Reserved        ;    Push  Reserved
PUSH      StartingPort    ;    Push  StartingPort
PUSH      NumPorts        ;    Push  NumPorts
PUSH      IOPortHook      ;    Push  IOPortHook
PUSH      EnableFlag      ;    Push  EnableFlag
 
CALL      VDHSetIOHookState      ;  Call  the  function </pre>
 
 
 
 
=== VDHSetIOHookState Parameter - Reserved ===
 
'''Reserved'''(DD) Reserved. Must be set to 0 (zero).
 
 
 
 
 
=== VDHSetIOHookState Parameter - StartingPort ===
 
'''StartingPort'''(DD) Starting port number.
 
 
 
 
 
=== VDHSetIOHookState Parameter - NumPorts ===
 
'''NumPorts'''(DD) Number of ports in the range.
 
 
 
 
 
=== VDHSetIOHookState Parameter - IOPortHook ===
 
'''IOPortHook'''(DD) Pointer used to install I/O hooks. This is used to verify that the calling virtual device driver is the one that installed the I/O hooks.
 
 
 
 
 
=== VDHSetIOHookState Parameter - EnableFlag ===
 
'''EnableFlag'''(DD) Flag for setting I/O hooks.
 
TRUE (Non-zero). Enable I/O hooks. <br />FALSE (0). Disable I/O hooks.
 
 
 
 
 
=== VDHSetIOHookState Return Value - rc ===
 
Success If the function was successful, it returns nothing.
 
Failure If ''IOPortHook''is invalid, or if ''StartingPort''or ''NumPorts''are out of range, or if ''StartingPort''and ''NumPorts''overlap a range of ports previously marked as ''VDHIIH_ALWAYS_TRAP''by ''VDHInstallIOHook'', a system halt occurs.
 
 
 
 
 
=== VDHSetIOHookState - Parameters ===
 
'''Reserved'''(DD) Reserved. Must be set to 0 (zero).
 
'''StartingPort'''(DD) Starting port number.
 
'''NumPorts'''(DD) Number of ports in the range.
 
'''IOPortHook'''(DD) Pointer used to install I/O hooks. This is used to verify that the calling virtual device driver is the one that installed the I/O hooks.
 
'''EnableFlag'''(DD) Flag for setting I/O hooks.
 
TRUE (Non-zero). Enable I/O hooks. <br />FALSE (0). Disable I/O hooks.
 
 
 
 
 
=== VDHSetIOHookState - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: If the ''IOPortHook''is in instance data, the address passed to ''VDHInstallIOHook''must be the same address passed to ''VDHRemoveIOHook''or ''VDHSetIOHookState''. When trapping is enabled, the I/O port hooks for the specified range get control when a DOS session does I/O to that range. When trapping is disabled, DOS session I/O goes directly to the physical hardware ports. None of the ports in the range can be marked as VDHIIH_ ALWAYS_TRAP by ''VDHInstallIOHook''.
 
 
 
 
 
=== VDHSetIOHookState - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetPriority ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  adjusts  a  DOS  session ' s  scheduler  priority  class  and  level .
Priority  levels  within  each  priority  class  range  from
0 - 31 .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetPriority : NEAR
VDMHandle          DD  ?      ;    Handle  to  the  DOS  session  with  the  priority  to  change
ActionClassFlag    DD  ?      ;    Dual  purpose  flag ,  Action  and  Class
NewPriority        DD  ?      ;    Change  from  the  DOS  session ' s  previous  priority  level
 
PUSH      VDMHandle          ;    Push  VDMHandle
PUSH      ActionClassFlag    ;    Push  ActionClassFlag
PUSH      NewPriority        ;    Push  NewPriority
 
CALL      VDHSetPriority          ;  Call  the  function </pre>
 
 
 
 
=== VDHSetPriority - Format ===
 
 
 
<pre class="western">/*
 
This  function  adjusts  a  DOS  session ' s  scheduler  priority  class  and  level .
Priority  levels  within  each  priority  class  range  from
0 - 31 .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetPriority : NEAR
VDMHandle          DD  ?      ;    Handle  to  the  DOS  session  with  the  priority  to  change
ActionClassFlag    DD  ?      ;    Dual  purpose  flag ,  Action  and  Class
NewPriority        DD  ?      ;    Change  from  the  DOS  session ' s  previous  priority  level
 
PUSH      VDMHandle          ;    Push  VDMHandle
PUSH      ActionClassFlag    ;    Push  ActionClassFlag
PUSH      NewPriority        ;    Push  NewPriority
 
CALL      VDHSetPriority          ;  Call  the  function </pre>
 
 
 
 
=== VDHSetPriority Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) Handle to the DOS session with the priority to change.
 
 
 
 
 
=== VDHSetPriority Parameter - ActionClassFlag ===
 
'''ActionClassFlag'''(DD) A dual-purpose flag.
 
The ''Class''component of ''ActionClassFlag''indicates the class to which the DOS session should be changed. The ''Action''component of the ''ActionClassFlag''allows the virtual device driver to manage when the priority is changed, and when to start, end, or continue use of the class. See &quot;Notes&quot; under Purpose.
 
The value of the ''Class''component can be one of the following:
 
VDHSP_TIME_CRITICAL Highest priority <br />VDHSP_SERVER Highest priority <br />VDHSP_REGULAR Highest priority <br />VDHSP_IDLE Lowest priority <br />VDHSP_NO_CHANGE Do not change the DOS session's class
 
The value of the ''Action''component can be one of the following:
 
VDHSP_START_USE Start use of a class <br />VDHSP_CONTINUE_USE Continue use of a class <br />VDHSP_END_USE End use of a class <br />VDHSP_DEFAULT_ACTION If no action is specified, the default class is changed
 
 
 
 
 
=== VDHSetPriority Parameter - NewPriority ===
 
'''NewPriority'''(DD) Change from the DOS session's previous priority level.
 
 
 
 
 
=== VDHSetPriority Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''VDMHandle''or ''ActionClassFlag''are invalid, a system halt occurs.
 
 
 
 
 
=== VDHSetPriority - Parameters ===
 
'''VDMHandle'''(DD) Handle to the DOS session with the priority to change.
 
'''ActionClassFlag'''(DD) A dual-purpose flag.
 
The ''Class''component of ''ActionClassFlag''indicates the class to which the DOS session should be changed. The ''Action''component of the ''ActionClassFlag''allows the virtual device driver to manage when the priority is changed, and when to start, end, or continue use of the class. See &quot;Notes&quot; under Purpose.
 
The value of the ''Class''component can be one of the following:
 
VDHSP_TIME_CRITICAL Highest priority <br />VDHSP_SERVER Highest priority <br />VDHSP_REGULAR Highest priority <br />VDHSP_IDLE Lowest priority <br />VDHSP_NO_CHANGE Do not change the DOS session's class
 
The value of the ''Action''component can be one of the following:
 
VDHSP_START_USE Start use of a class <br />VDHSP_CONTINUE_USE Continue use of a class <br />VDHSP_END_USE End use of a class <br />VDHSP_DEFAULT_ACTION If no action is specified, the default class is changed
 
'''NewPriority'''(DD) Change from the DOS session's previous priority level.
 
 
 
 
 
=== VDHSetPriority - Purpose ===
 
Context Issues: This function can be called in the task or interrupt contexts.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: A count of the current users is maintained at each class. The actual priority class in effect at any time is always the highest priority class with current declared users. When there are no declared users, the default class is used. Changes to a class other than the effective class are made to saved values. These changes take effect when the class becomes the effective class.
 
The caller must signal when it begins use of the class, when it makes changes within the class, and when it finishes with the class. The typical user would make one or more changes to priority at a particular class, and finish the series of changes at the class. The virtual device driver uses the VDHSP_START_USE and VDHSP_END_USE flags at the first and last calls within the class, and the VDHSP_CONTINUE_USE flag for changes in between.
 
The default class is normally VDHSP_REGULAR unless the class or ''NewPriority''is changed without declaring a user (that is, without specifying a start, continue, or end action flag). This allows a user interface to adjust the default priority of a DOS session.
 
 
 
 
 
=== VDHSetPriority - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetVIRR ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  sets  the  Virtual  Interrupt  Request  Register  ( VIRR )  in
the  Virtual  Programmable  Interrupt  Controller  ( VPIC )  of  the  specified
DOS  session  for  the  IRQ  specified .
This  causes  an  interrupt  to  be  simulated  to  the  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetVIRR : NEAR
VDMHandle    DD  ?      ;    DOS  session  handle
IRQHandle    DD  ?      ;    Handle  from  VDHOpenVIRQ
 
PUSH      VDMHandle    ;    Push  VDMHandle
PUSH      IRQHandle    ;    Push  IRQHandle
 
CALL      VDHSetVIRR    ;  Call  the  function </pre>
 
 
 
 
=== VDHSetVIRR - Format ===
 
 
 
<pre class="western">/*
 
This  function  sets  the  Virtual  Interrupt  Request  Register  ( VIRR )  in
the  Virtual  Programmable  Interrupt  Controller  ( VPIC )  of  the  specified
DOS  session  for  the  IRQ  specified .
This  causes  an  interrupt  to  be  simulated  to  the  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetVIRR : NEAR
VDMHandle    DD  ?      ;    DOS  session  handle
IRQHandle    DD  ?      ;    Handle  from  VDHOpenVIRQ
 
PUSH      VDMHandle    ;    Push  VDMHandle
PUSH      IRQHandle    ;    Push  IRQHandle
 
CALL      VDHSetVIRR    ;  Call  the  function </pre>
 
 
 
 
=== VDHSetVIRR Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
 
 
 
 
=== VDHSetVIRR Parameter - IRQHandle ===
 
'''IRQHandle'''(DD) IRQ handle from ''VDHOpenVIRQ''.
 
 
 
 
 
=== VDHSetVIRR Return Value - rc ===
 
Success If the function was successful, it returns nothing.
 
Failure If either of the parameters is invalid, a system halt occurs.
 
 
 
 
 
=== VDHSetVIRR - Parameters ===
 
'''VDMHandle'''(DD) DOS session handle. A value of 0 (zero) indicates the current DOS session.
 
'''IRQHandle'''(DD) IRQ handle from ''VDHOpenVIRQ''.
 
 
 
 
 
=== VDHSetVIRR - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: If the interrupt request has not been cleared when the DOS session issues an End-Of-Interrupt (EOI), another interrupt will be simulated to the DOS session.
 
 
 
 
 
=== VDHSetVIRR - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetVPMExcept ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  sets  the  current  value  in  the  protected - mode  exception
table .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetVPMExcept : NEAR
Vector            DD  ?      ;    Interrupt  vector  number
HandlerAddress    DQ  ?      ;    Far32  handler  address
Flag              DB  ?      ;    Flag  indicating  exception  handler
 
PUSH      Vector            ;    Push  Vector
PUSH      HandlerAddress    ;    Push  HandlerAddress
PUSH      Flag              ;    Push  Flag
 
CALL      VDHSetVPMExcept        ;  Call  the  function </pre>
 
 
 
 
=== VDHSetVPMExcept - Format ===
 
 
 
<pre class="western">/*
 
This  function  sets  the  current  value  in  the  protected - mode  exception
table .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetVPMExcept : NEAR
Vector            DD  ?      ;    Interrupt  vector  number
HandlerAddress    DQ  ?      ;    Far32  handler  address
Flag              DB  ?      ;    Flag  indicating  exception  handler
 
PUSH      Vector            ;    Push  Vector
PUSH      HandlerAddress    ;    Push  HandlerAddress
PUSH      Flag              ;    Push  Flag
 
CALL      VDHSetVPMExcept        ;  Call  the  function </pre>
 
 
 
 
=== VDHSetVPMExcept Parameter - Vector ===
 
'''Vector'''(DD) Interrupt vector number.
 
 
 
 
 
=== VDHSetVPMExcept Parameter - HandlerAddress ===
 
'''HandlerAddress'''(DQ) Far32 handler address.
 
 
 
 
 
=== VDHSetVPMExcept Parameter - Flag ===
 
'''Flag'''(DB) Flag indicating the kind of exception handler being registered.
 
Possible value:
 
VPMXCPT32 A 32-bit handler is being registered.
 
 
 
 
 
=== VDHSetVPMExcept Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHSetVPMExcept - Parameters ===
 
'''Vector'''(DD) Interrupt vector number.
 
'''HandlerAddress'''(DQ) Far32 handler address.
 
'''Flag'''(DB) Flag indicating the kind of exception handler being registered.
 
Possible value:
 
VPMXCPT32 A 32-bit handler is being registered.
 
 
 
 
 
=== VDHSetVPMExcept - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: There must be a DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHSetVPMExcept - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSetVPMIntVector ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  sets  the  application  Ring  3  handler  in  the  protected - mode
interrupt  chain .
This  is  used  only  for  DOS  Protect  Mode  Interface  ( DPMI )  support .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetVPMIntVector : NEAR
Vector            DD  ?      ;    Interrupt  vector  number
HandlerAddress    DQ  ?      ;    Far32  handler  address
Flag              DB  ?      ;    Flag .
 
PUSH      Vector            ;    Push  Vector
PUSH      HandlerAddress    ;    Push  HandlerAddress
PUSH      Flag              ;    Push  Flag
 
CALL      VDHSetVPMIntVector        ;  Call  the  function </pre>
 
 
 
 
=== VDHSetVPMIntVector - Format ===
 
 
 
<pre class="western">/*
 
This  function  sets  the  application  Ring  3  handler  in  the  protected - mode
interrupt  chain .
This  is  used  only  for  DOS  Protect  Mode  Interface  ( DPMI )  support .
* /
 
include  mvdm . inc
 
EXTERN    VDHSetVPMIntVector : NEAR
Vector            DD  ?      ;    Interrupt  vector  number
HandlerAddress    DQ  ?      ;    Far32  handler  address
Flag              DB  ?      ;    Flag .
 
PUSH      Vector            ;    Push  Vector
PUSH      HandlerAddress    ;    Push  HandlerAddress
PUSH      Flag              ;    Push  Flag
 
CALL      VDHSetVPMIntVector        ;  Call  the  function </pre>
 
 
 
 
=== VDHSetVPMIntVector Parameter - Vector ===
 
'''Vector'''(DD) Interrupt vector number.
 
 
 
 
 
=== VDHSetVPMIntVector Parameter - HandlerAddress ===
 
'''HandlerAddress'''(DQ) Far32 handler address.
 
 
 
 
 
=== VDHSetVPMIntVector Parameter - Flag ===
 
'''Flag'''(DB) Flag.
 
 
 
 
 
=== VDHSetVPMIntVector Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero).
 
 
 
 
 
=== VDHSetVPMIntVector - Parameters ===
 
'''Vector'''(DD) Interrupt vector number.
 
'''HandlerAddress'''(DQ) Far32 handler address.
 
'''Flag'''(DB) Flag.
 
 
 
 
 
=== VDHSetVPMIntVector - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: There must be a DPMI client running in the DOS session before calling this function.
 
 
 
 
 
=== VDHSetVPMIntVector - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSwitchToVPM ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  switches  the  current  DOS  session  into  protected  mode .
This  assumes  that  the  appropriate  initializations  have  already  been
performed .
* /
 
include  mvdm . inc
 
EXTERN    VDHSwitchToVPM : NEAR
                DD  ?
 
PUSH                      ;    Push
 
CALL      VDHSwitchToVPM      ;  Call  the  function </pre>
 
 
 
 
=== VDHSwitchToVPM - Format ===
 
 
 
<pre class="western">/*
 
This  function  switches  the  current  DOS  session  into  protected  mode .
This  assumes  that  the  appropriate  initializations  have  already  been
performed .
* /
 
include  mvdm . inc
 
EXTERN    VDHSwitchToVPM : NEAR
                DD  ?
 
PUSH                      ;    Push
 
CALL      VDHSwitchToVPM      ;  Call  the  function </pre>
 
 
 
 
=== VDHSwitchToVPM Parameter - ===
 
(DD) None.
 
 
 
 
 
=== VDHSwitchToVPM Return Value - ===
 
None.
 
 
 
 
 
=== VDHSwitchToVPM - Parameters ===
 
(DD) None.
 
 
 
 
 
=== VDHSwitchToVPM - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHSwitchToVPM - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHSwitchToV86 ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  switches  the  current  DOS  session  to  V86  mode .
* /
 
include  mvdm . inc
 
EXTERN    VDHSwitchToV86 : NEAR
                DD  ?
 
PUSH                      ;    Push
 
CALL      VDHSwitchToV86      ;  Call  the  function </pre>
 
 
 
 
=== VDHSwitchToV86 - Format ===
 
 
 
<pre class="western">/*
 
This  function  switches  the  current  DOS  session  to  V86  mode .
* /
 
include  mvdm . inc
 
EXTERN    VDHSwitchToV86 : NEAR
                DD  ?
 
PUSH                      ;    Push
 
CALL      VDHSwitchToV86      ;  Call  the  function </pre>
 
 
 
 
=== VDHSwitchToV86 Parameter - ===
 
(DD) None.
 
 
 
 
 
=== VDHSwitchToV86 Return Value - ===
 
None.
 
 
 
 
 
=== VDHSwitchToV86 - Parameters ===
 
(DD) None.
 
 
 
 
 
=== VDHSwitchToV86 - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHSwitchToV86 - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHThawVDM ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  reverses  the  effect  of  VDHFreezeVDM .
The  specified
DOS  session  is  allowed  to  run  when  the  freeze  count  becomes
0  ( zero ) .
* /
 
include  mvdm . inc
 
EXTERN    VDHThawVDM : NEAR
VDMHandle    DD  ?      ;    Handle  to  the  DOS  session  to  thaw
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHThawVDM    ;  Call  the  function </pre>
 
 
 
 
=== VDHThawVDM - Format ===
 
 
 
<pre class="western">/*
 
This  function  reverses  the  effect  of  VDHFreezeVDM .
The  specified
DOS  session  is  allowed  to  run  when  the  freeze  count  becomes
0  ( zero ) .
* /
 
include  mvdm . inc
 
EXTERN    VDHThawVDM : NEAR
VDMHandle    DD  ?      ;    Handle  to  the  DOS  session  to  thaw
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHThawVDM    ;  Call  the  function </pre>
 
 
 
 
=== VDHThawVDM Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) Handle to the DOS session to allow to execute (thaw).
 
 
 
 
 
=== VDHThawVDM Return Value - rc ===
 
Success If the function is successful, it returns nothing. The freeze count for the DOS session is decremented.
 
Failure If ''VDMHandle''is an invalid handle, a system halt occurs.
 
 
 
 
 
=== VDHThawVDM - Parameters ===
 
'''VDMHandle'''(DD) Handle to the DOS session to allow to execute (thaw).
 
 
 
 
 
=== VDHThawVDM - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: This function does nothing if called on behalf of a DOS session that is not frozen. See [[00477.htm|VDHFreezeVDM]]for a full discussion of freeze counting.
 
 
 
 
 
=== VDHThawVDM - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHUnlockMem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  reverses  the  effect  of  VDHLockMem ,
unlocking  a  previously  locked  area  of  memory .
* /
 
include  mvdm . inc
 
EXTERN    VDHUnlockMem : NEAR
LockHandle    DD  ?      ;    Lock  handle  from  VDHLockMem
 
PUSH      LockHandle    ;    Push  LockHandle
 
CALL      VDHUnlockMem    ;  Call  the  function </pre>
 
 
 
 
=== VDHUnlockMem - Format ===
 
 
 
<pre class="western">/*
 
This  function  reverses  the  effect  of  VDHLockMem ,
unlocking  a  previously  locked  area  of  memory .
* /
 
include  mvdm . inc
 
EXTERN    VDHUnlockMem : NEAR
LockHandle    DD  ?      ;    Lock  handle  from  VDHLockMem
 
PUSH      LockHandle    ;    Push  LockHandle
 
CALL      VDHUnlockMem    ;  Call  the  function </pre>
 
 
 
 
=== VDHUnlockMem Parameter - LockHandle ===
 
'''LockHandle'''(DD) Lock handle of a locked memory area. Originally obtained from ''VDHLockMem''.
 
 
 
 
 
=== VDHUnlockMem Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure An invalid lock handle causes a system halt to occur.
 
 
 
 
 
=== VDHUnlockMem - Parameters ===
 
'''LockHandle'''(DD) Lock handle of a locked memory area. Originally obtained from ''VDHLockMem''.
 
 
 
 
 
=== VDHUnlockMem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Because lock handles are global, this function can be made in any task context.
 
 
 
 
 
=== VDHUnlockMem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHUnreservePages ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  unreserves  pages  that  were  previously  reserved  with
VDHReservePages .
The  starting  address  and  size  must  be  identical
to  the  previous  corresponding  call  to  VDHReservePages .
Note  that
any  mapping  made  earlier  on  this  region  is  unmapped  before  calling
this  function .
* /
 
include  mvdm . inc
 
EXTERN    VDHUnreservePages : NEAR
StartingAddress    DD  ?      ;    Starting  address  of  the  region  to  unreserve
NumPages          DD  ?      ;    Size  of  the  region  to  unreserve ,  in  pages
 
PUSH      StartingAddress    ;    Push  StartingAddress
PUSH      NumPages          ;    Push  NumPages
 
CALL      VDHUnreservePages          ;  Call  the  function </pre>
 
 
 
 
=== VDHUnreservePages - Format ===
 
 
 
<pre class="western">/*
 
This  function  unreserves  pages  that  were  previously  reserved  with
VDHReservePages .
The  starting  address  and  size  must  be  identical
to  the  previous  corresponding  call  to  VDHReservePages .
Note  that
any  mapping  made  earlier  on  this  region  is  unmapped  before  calling
this  function .
* /
 
include  mvdm . inc
 
EXTERN    VDHUnreservePages : NEAR
StartingAddress    DD  ?      ;    Starting  address  of  the  region  to  unreserve
NumPages          DD  ?      ;    Size  of  the  region  to  unreserve ,  in  pages
 
PUSH      StartingAddress    ;    Push  StartingAddress
PUSH      NumPages          ;    Push  NumPages
 
CALL      VDHUnreservePages          ;  Call  the  function </pre>
 
 
 
 
=== VDHUnreservePages Parameter - StartingAddress ===
 
'''StartingAddress'''(DD) Starting address of the region to unreserve. Must be less than 110000H (1MB+64KB) and must be page-aligned. In addition, ''StartingAddress''must match a previous ''VDHReservePages''call.
 
 
 
 
 
=== VDHUnreservePages Parameter - NumPages ===
 
'''NumPages'''(DD) Size, in pages, of the region to unreserve. Must match the corresponding parameter to a previous call to ''VDHReservePages''.
 
 
 
 
 
=== VDHUnreservePages Return Value - rc ===
 
Success If the function is successful, it returns nothing.
 
Failure If ''StartingAddress''or ''NumPages''is invalid, or if they were not used together in an earlier call to ''VDHReservePages'', a system halt occurs.
 
 
 
 
 
=== VDHUnreservePages - Parameters ===
 
'''StartingAddress'''(DD) Starting address of the region to unreserve. Must be less than 110000H (1MB+64KB) and must be page-aligned. In addition, ''StartingAddress''must match a previous ''VDHReservePages''call.
 
'''NumPages'''(DD) Size, in pages, of the region to unreserve. Must match the corresponding parameter to a previous call to ''VDHReservePages''.
 
 
 
 
 
=== VDHUnreservePages - Purpose ===
 
Context Issues: This function can be called in the initialization or DOS session-task context (DOS session creation). In the initialization context, memory can be unreserved only from the global linear memory map. In the DOS session-task context, memory can be unreserved only from the local linear memory map.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: ''StartingAddress''must be less than 110000H(1MB+64KB) and must be page -aligned. Additionally, ''StartingAddress''must match a previous call to ''VDHReservePages''. ''NumPages''must match the corresponding parameter to a previous call to ''VDHReservePages''.
 
 
 
 
 
=== VDHUnreservePages - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHWaitEventSem ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  is  used  to  wait  on  an  event  semaphore .
If  the
semaphore  is  posted ,  it  will  return  immediately .
* /
 
include  mvdm . inc
 
EXTERN    VDHWaitEventSem : NEAR
EventSemHandle    DD  ?      ;    Event  semaphore  handle
Timeout          DD  ?      ;    Timeout  ( in  milliseconds )
 
PUSH      EventSemHandle    ;    Push  EventSemHandle
PUSH      Timeout          ;    Push  Timeout
 
CALL      VDHWaitEventSem        ;  Call  the  function </pre>
 
 
 
 
=== VDHWaitEventSem - Format ===
 
 
 
<pre class="western">/*
 
This  function  is  used  to  wait  on  an  event  semaphore .
If  the
semaphore  is  posted ,  it  will  return  immediately .
* /
 
include  mvdm . inc
 
EXTERN    VDHWaitEventSem : NEAR
EventSemHandle    DD  ?      ;    Event  semaphore  handle
Timeout          DD  ?      ;    Timeout  ( in  milliseconds )
 
PUSH      EventSemHandle    ;    Push  EventSemHandle
PUSH      Timeout          ;    Push  Timeout
 
CALL      VDHWaitEventSem        ;  Call  the  function </pre>
 
 
 
 
=== VDHWaitEventSem Parameter - EventSemHandle ===
 
'''EventSemHandle'''(DD) Event semaphore handle.
 
 
 
 
 
=== VDHWaitEventSem Parameter - Timeout ===
 
'''Timeout'''(DD) Number of milliseconds to wait before timing out.
 
 
 
 
 
=== VDHWaitEventSem Return Value - rc ===
 
Success If the function is successful, it returns 1 (one).
 
Failure If the function fails, it returns 0 (zero). ''VDHGetError''should be called to determine the nature of the problem. If ''EventSemHandle''is invalid , a system halt occurs.
 
 
 
 
 
=== VDHWaitEventSem - Parameters ===
 
'''EventSemHandle'''(DD) Event semaphore handle.
 
'''Timeout'''(DD) Number of milliseconds to wait before timing out.
 
 
 
 
 
=== VDHWaitEventSem - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function. If ''Timeout''is 0 (zero), the caller will not block; however, ERROR_TIMEOUT is returned. If ''Timeout''is -1, the caller is blocked until the semaphore is posted. Otherwise, the caller blocks for the time specified (in milliseconds) in ''Timeout''.
 
 
 
 
 
=== VDHWaitEventSem - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHWaitVIRRs ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  waits  until  any  virtual  interrupt  is  simulated  to  the
current  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHWaitVIRRs : NEAR
PostInFcnHook    DD  ?      ;    Hook  handle
 
PUSH      PostInFcnHook    ;    Push  PostInFcnHook
 
CALL      VDHWaitVIRRs        ;  Call  the  function </pre>
 
 
 
 
=== VDHWaitVIRRs - Format ===
 
 
 
<pre class="western">/*
 
This  function  waits  until  any  virtual  interrupt  is  simulated  to  the
current  DOS  session .
* /
 
include  mvdm . inc
 
EXTERN    VDHWaitVIRRs : NEAR
PostInFcnHook    DD  ?      ;    Hook  handle
 
PUSH      PostInFcnHook    ;    Push  PostInFcnHook
 
CALL      VDHWaitVIRRs        ;  Call  the  function </pre>
 
 
 
 
=== VDHWaitVIRRs Parameter - PostInFcnHook ===
 
'''PostInFcnHook'''(DD) Hook handle of a routine that is to be called after interrupts are simulated.
 
 
 
 
 
=== VDHWaitVIRRs Return Value - rc ===
 
Success The function returns a nonzero value, if it woke up because of a simulated interrupt. If it woke up because of a ''VDHWakeVIRRs''call, the function returns 0 (zero).
 
Failure If the function fails, it returns nothing.
 
 
 
 
 
=== VDHWaitVIRRs - Parameters ===
 
'''PostInFcnHook'''(DD) Hook handle of a routine that is to be called after interrupts are simulated.
 
 
 
 
 
=== VDHWaitVIRRs - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: The hook handle must be allocated as a VDH_WAITVIRRS_HOOK type. This function is intended for virtual device drivers that need to simulate a spin loop without stopping virtual interrupt simulation. This allows the virtual device driver to be compatible with DOS but avoid wasting CPU time in a spin loop.
 
The DOS session's interrupts must be enabled, using ''VDHSetFlags'', before this service is used.
 
Generally, the virtual device driver will be in a loop when calling this function. When it returns a nonzero value, the virtual device driver returns to V86 mode so that the interrupt can be simulated. The hook function passed to this service is executed after all interrupts are simulated. When this function returns 0 (zero), it is because some other portion of the virtual device driver (likely in response to a physical hardware interrupt) has determined that the DOS session no longer needs to spin. The virtual device driver exits the loop at this point.
 
The virtual keyboard device driver behaves in this manner in order to emulate the ROM BIOS Read Keyboard function (INT 16H, AH=00) without using excessive CPU time, by allowing the ROM BIOS to spin out in V86 mode, or stopping simulated interrupts by performing a ''VDHWaitEventSem''.
 
 
 
 
 
=== VDHWaitVIRRs - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHWakeIdle ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  notes  that  the  DOS  session  is  busy  ( doing  useful  work ) .
If  the
DOS  session  is  currently  sleeping  or  running  at  a  lower  priority  because  of  the
polling  activities ,  the  DOS  session  is  awakened ,  its  priority  is  restored ,  and
it  is  no  longer  considered  idle .
* /
 
include  mvdm . inc
 
EXTERN    VDHWakeIdle : NEAR
VDMHandle    DD  ?      ;    Handle  to  the  DOS  session  to  wake  up
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHWakeIdle    ;  Call  the  function </pre>
 
 
 
 
=== VDHWakeIdle - Format ===
 
 
 
<pre class="western">/*
 
This  function  notes  that  the  DOS  session  is  busy  ( doing  useful  work ) .
If  the
DOS  session  is  currently  sleeping  or  running  at  a  lower  priority  because  of  the
polling  activities ,  the  DOS  session  is  awakened ,  its  priority  is  restored ,  and
it  is  no  longer  considered  idle .
* /
 
include  mvdm . inc
 
EXTERN    VDHWakeIdle : NEAR
VDMHandle    DD  ?      ;    Handle  to  the  DOS  session  to  wake  up
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHWakeIdle    ;  Call  the  function </pre>
 
 
 
 
=== VDHWakeIdle Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) Handle to the DOS session to be awakened.
 
 
 
 
 
=== VDHWakeIdle Return Value - ===
 
None.
 
 
 
 
 
=== VDHWakeIdle - Parameters ===
 
'''VDMHandle'''(DD) Handle to the DOS session to be awakened.
 
 
 
 
 
=== VDHWakeIdle - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHWakeIdle - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHWakeVIRRs ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  wakes  up  a  DOS  session  that  is  waiting  with  the
VDHWaitVIRRs
service .
See
VDHWaitVIRRs
for  a  full  description  of  the  use  of  this  function .
* /
 
include  mvdm . inc
 
EXTERN    VDHWakeVIRRs : NEAR
VDMHandle    DD  ?      ;    Handle  of  the  DOS  session  to  wake  up
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHWakeVIRRs    ;  Call  the  function </pre>
 
 
 
 
=== VDHWakeVIRRs - Format ===
 
 
 
<pre class="western">/*
 
This  function  wakes  up  a  DOS  session  that  is  waiting  with  the
VDHWaitVIRRs
service .
See
VDHWaitVIRRs
for  a  full  description  of  the  use  of  this  function .
* /
 
include  mvdm . inc
 
EXTERN    VDHWakeVIRRs : NEAR
VDMHandle    DD  ?      ;    Handle  of  the  DOS  session  to  wake  up
 
PUSH      VDMHandle    ;    Push  VDMHandle
 
CALL      VDHWakeVIRRs    ;  Call  the  function </pre>
 
 
 
 
=== VDHWakeVIRRs Parameter - VDMHandle ===
 
'''VDMHandle'''(DD) Handle of the DOS session to be awakened.
 
 
 
 
 
=== VDHWakeVIRRs Return Value - rc ===
 
Success If the function was successful, it returns nothing.
 
Failure If ''VDMHandle''is invalid, a system halt occurs.
 
 
 
 
 
=== VDHWakeVIRRs - Parameters ===
 
'''VDMHandle'''(DD) Handle of the DOS session to be awakened.
 
 
 
 
 
=== VDHWakeVIRRs - Purpose ===
 
Context Issues: This function can be called in the task or interrupt context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: Use with caution because it wakes up every virtual device driver that is waiting on a ''VDHWaitVIRRs''.
 
 
 
 
 
=== VDHWakeVIRRs - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHWrite ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  writes  bytes  to  a  file  or  device  previously  opened  by
VDHOpen .
* /
 
include  mvdm . inc
 
EXTERN    VDHWrite : NEAR
FileHandle        DW  ?      ;    Handle  to  the  file  or  device  to  write  to
WriteBufferPtr    DD  ?      ;    Pointer  to  the  buffer  to  write
NumBytes          DD  ?      ;    Number  of  bytes  to  write
 
PUSH      FileHandle        ;    Push  FileHandle
PUSH      WriteBufferPtr    ;    Push  WriteBufferPtr
PUSH      NumBytes          ;    Push  NumBytes
 
CALL      VDHWrite        ;  Call  the  function </pre>
 
 
 
 
=== VDHWrite - Format ===
 
 
 
<pre class="western">/*
 
This  function  writes  bytes  to  a  file  or  device  previously  opened  by
VDHOpen .
* /
 
include  mvdm . inc
 
EXTERN    VDHWrite : NEAR
FileHandle        DW  ?      ;    Handle  to  the  file  or  device  to  write  to
WriteBufferPtr    DD  ?      ;    Pointer  to  the  buffer  to  write
NumBytes          DD  ?      ;    Number  of  bytes  to  write
 
PUSH      FileHandle        ;    Push  FileHandle
PUSH      WriteBufferPtr    ;    Push  WriteBufferPtr
PUSH      NumBytes          ;    Push  NumBytes
 
CALL      VDHWrite        ;  Call  the  function </pre>
 
 
 
 
=== VDHWrite Parameter - FileHandle ===
 
'''FileHandle'''(DW) Handle to the file or device to write to.
 
 
 
 
 
=== VDHWrite Parameter - WriteBufferPtr ===
 
'''WriteBufferPtr'''(DD) Pointer to the buffer to write.
 
 
 
 
 
=== VDHWrite Parameter - NumBytes ===
 
'''NumBytes'''(DD) Number of bytes to write.
 
 
 
 
 
=== VDHWrite Return Value - rc ===
 
Success If the function is successful, it returns a count of the bytes written. This can be equal to 0 (zero).
 
Failure If the function fails, it returns 0FFFFFFFFH. ''VDHGetError''should be called to determine the nature of the problem. If ''FileHandle''is invalid, or this function is called in any context except DOS session-task, a system halt occurs.
 
 
 
 
 
=== VDHWrite - Parameters ===
 
'''FileHandle'''(DW) Handle to the file or device to write to.
 
'''WriteBufferPtr'''(DD) Pointer to the buffer to write.
 
'''NumBytes'''(DD) Number of bytes to write.
 
 
 
 
 
=== VDHWrite - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
 
 
 
 
=== VDHWrite - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHWriteUBuf ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  writes  to  protected - mode  address  space  as  if  access  were
done  at  Ring  3 .
This  means  checking  for  supervisor  and  read - only
faults ,  and  trapping  any  other  faults .
All  faults  are  passed  on  to  the
DOS  session  application  handler  through  VDHRaiseException .
* /
 
include  mvdm . inc
 
EXTERN    VDHWriteUBuf : NEAR
SourceBuffer    DD  ?      ;    Source  buffer  from  which  to  copy
ByteCount        DD  ?      ;    Count  of  bytes
Selector        DW  ?      ;    Application  selector
OffsetPointer    DD  ?      ;    Address  of  the  variable  containing  the  offset
Flag              DD  ?      ;    Flag  for  checking  controls
 
PUSH      SourceBuffer    ;    Push  SourceBuffer
PUSH      ByteCount        ;    Push  ByteCount
PUSH      Selector        ;    Push  Selector
PUSH      OffsetPointer    ;    Push  OffsetPointer
PUSH      Flag              ;    Push  Flag
 
CALL      VDHWriteUBuf        ;  Call  the  function </pre>
 
 
 
 
=== VDHWriteUBuf - Format ===
 
 
 
<pre class="western">/*
 
This  function  writes  to  protected - mode  address  space  as  if  access  were
done  at  Ring  3 .
This  means  checking  for  supervisor  and  read - only
faults ,  and  trapping  any  other  faults .
All  faults  are  passed  on  to  the
DOS  session  application  handler  through  VDHRaiseException .
* /
 
include  mvdm . inc
 
EXTERN    VDHWriteUBuf : NEAR
SourceBuffer    DD  ?      ;    Source  buffer  from  which  to  copy
ByteCount        DD  ?      ;    Count  of  bytes
Selector        DW  ?      ;    Application  selector
OffsetPointer    DD  ?      ;    Address  of  the  variable  containing  the  offset
Flag              DD  ?      ;    Flag  for  checking  controls
 
PUSH      SourceBuffer    ;    Push  SourceBuffer
PUSH      ByteCount        ;    Push  ByteCount
PUSH      Selector        ;    Push  Selector
PUSH      OffsetPointer    ;    Push  OffsetPointer
PUSH      Flag              ;    Push  Flag
 
CALL      VDHWriteUBuf        ;  Call  the  function </pre>
 
 
 
 
=== VDHWriteUBuf Parameter - SourceBuffer ===
 
'''SourceBuffer'''(DD) Source buffer from which to copy.
 
 
 
 
 
=== VDHWriteUBuf Parameter - ByteCount ===
 
'''ByteCount'''(DD) Count of bytes.
 
 
 
 
 
=== VDHWriteUBuf Parameter - Selector ===
 
'''Selector'''(DW) Application selector.
 
 
 
 
 
=== VDHWriteUBuf Parameter - OffsetPointer ===
 
'''OffsetPointer'''(DD) Address of the variable containing the offset for the start of the write.
 
 
 
 
 
=== VDHWriteUBuf Parameter - Flag ===
 
'''Flag'''(DD) Checking control.
 
Possible values are:
 
VPM_PROT_READ Check for read. <br />VPM_PROT_WRITE Check for write. <br />VPM_FAULT_IF_SU_SET Fault, if supervisor pages. <br />VPM_FAULT_IF_RO Fault, if writing to read-only descriptor. <br />VPM_SEL_PRESENT Caller knows descriptor is present. <br />VPM_SEL_WRITEABLE Caller knows descriptor is writable. <br />VPM_SEL_IS_SS Selector is client's stack. <br />VPM_XCPTRET_ALT After exception, return to alternate mode. For example, if the client was in protected mode when the service was called, return in V86 mode after the exception is handled.
 
 
 
 
 
=== VDHWriteUBuf Return Value - rc ===
 
Success If the function is successful, it returns a nonzero value.
 
Failure If the function fails, it returns 0 (zero) if there is a bad address reference, which causes a fault. In such a case, ''OffsetPointer''is updated with the address of the fault. For Selector Faults, ''OffsetPointer''remains unchanged.
 
 
 
 
 
=== VDHWriteUBuf - Parameters ===
 
'''SourceBuffer'''(DD) Source buffer from which to copy.
 
'''ByteCount'''(DD) Count of bytes.
 
'''Selector'''(DW) Application selector.
 
'''OffsetPointer'''(DD) Address of the variable containing the offset for the start of the write.
 
'''Flag'''(DD) Checking control.
 
Possible values are:
 
VPM_PROT_READ Check for read. <br />VPM_PROT_WRITE Check for write. <br />VPM_FAULT_IF_SU_SET Fault, if supervisor pages. <br />VPM_FAULT_IF_RO Fault, if writing to read-only descriptor. <br />VPM_SEL_PRESENT Caller knows descriptor is present. <br />VPM_SEL_WRITEABLE Caller knows descriptor is writable. <br />VPM_SEL_IS_SS Selector is client's stack. <br />VPM_XCPTRET_ALT After exception, return to alternate mode. For example, if the client was in protected mode when the service was called, return in V86 mode after the exception is handled.
 
 
 
 
 
=== VDHWriteUBuf - Purpose ===
 
Context Issues: This function can be called only in the DOS session-task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: When the routine fails, the caller must clean up and exit so that the exception can be simulated to the user.
 
 
 
 
 
=== VDHWriteUBuf - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
 
 
 
=== VDHYield ===
 
 
-----
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
-----
 
 
 
<pre class="western">/*
 
This  function  yields  the  processor  to  any  other  thread  of  equal  or
higher  priority .
* /
 
include  mvdm . inc
 
EXTERN    VDHYield : NEAR
OptionFlag    DD  ?      ;    Yield  options
 
PUSH      OptionFlag    ;    Push  OptionFlag
 
CALL      VDHYield    ;  Call  the  function </pre>
 
 
 
 
=== VDHYield - Format ===
 
 
 
<pre class="western">/*
 
This  function  yields  the  processor  to  any  other  thread  of  equal  or
higher  priority .
* /
 
include  mvdm . inc
 
EXTERN    VDHYield : NEAR
OptionFlag    DD  ?      ;    Yield  options
 
PUSH      OptionFlag    ;    Push  OptionFlag
 
CALL      VDHYield    ;  Call  the  function </pre>
 
 
 
 
=== VDHYield Parameter - OptionFlag ===
 
'''OptionFlag'''(DD) Yield options.
 
Possible value:
 
VDH_YIELD_TIME_CRITICAL Yield only to time-critical threads.
 
 
 
 
 
=== VDHYield Return Value - ===
 
None.
 
 
 
 
 
=== VDHYield - Parameters ===
 
'''OptionFlag'''(DD) Yield options.
 
Possible value:
 
VDH_YIELD_TIME_CRITICAL Yield only to time-critical threads.
 
 
 
 
 
=== VDHYield - Purpose ===
 
Context Issues: This function can be called only in the task context.
 
DOS Session Terminations: There are no DOS session termination implications for this function.
 
Notes: If ''OptionFlag''is VDH_YIELD_TIME_CRITICAL, and no time-critical thread is able to run, the caller keeps the CPU.
 
 
 
 
 
=== VDHYield - Topics ===
 
Select an item:
 
<pre class="western">Format
Parameters
Return Codes
Purpose
Glossary </pre>
 
=Notices =
 
'''OS/2 Developer Connection Device Driver Kit, Version 4 Edition (June 1996)'''
 
'''The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law:'''INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
 
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.
 
It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.
 
Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.
 
=== Copyright Notices ===
 
COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.
 
Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: &quot;(C) (your company name) (year). All rights reserved.&quot;
 
'''(C) Copyright International Business Machines Corporation 1996. All rights reserved.'''<br />Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
 
 
 
 
 
=== Disclaimers ===
 
References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products , except those expressly designated by IBM, are the responsibility of the user.
 
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:
 
IBM Director of Licensing <br />IBM Corporation <br />500 Columbus Avenue <br />Thornwood, NY 10594 <br />U.S.A.
 
 
 
 
 
=== Trademarks ===
 
The following terms are trademarks of the IBM Corporation in the United States or other countries or both:
 
* IBM
* Multimedia Presentation Manager/2
* OS/2
* Ultimotion
The following terms are trademarks of other companies:
 
* Helvetica Linotype Company
* MASM Microsoft Corporation
* Mitsumi Mitsumi Denki Kabushki Kaisha
* Panasonic Matsushita Electric Industrial Co., Ltd.
* OPTi OPTi, Inc.
* Pioneer Pioneer Electric Corporation
* ProAudio Spectrum Media Vision, Inc.
* ProAudio Spectrum 16 Media Vision, Inc.
* QuickVia Jovian Logic Corp.
* ReelMagic Sigma Designs, Inc.
* Sound Blaster Creative Technology Ltd.
* SuperVia Jovian Logic Corp.
* Super VideoWindows New Media Graphics Corporation
* Video Blaster Creative Technology, Inc.
* Yamaha Yamaha Corporation
 
Windows is a trademark of Microsoft Corporation.
 
UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited.
 
Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others. *.im (ddkglos scrpol)
 
= Glossary =
 
This glossary contains terms and definitions that are, for the most part, used for OS/2 products. This is not a complete dictionary of computer terms .
 
=== Introduction ===
 
This glossary defines many of the terms used in this book. It includes terms and definitions from the ''IBM Dictionary of Computing'', as well as terms specific to the Presentation Manager, but it is not a complete glossary for OS/2.
 
Other primary sources for these definitions are:
 
*The ''American National Standard Dictionary for Information Systems'', ANSI X3 .172-1990, copyrighted 1990 by the American National Standards Institute, 11 West 42nd Street, New York, New York 10036. These definitions are identified by the symbol (A) after the definition.
 
*The ''Information Technology Vocabulary'', developed by Subcommittee 1, Joint Technical Committee 1, of the International Organization for Standardization and the International Electrotechnical Commission (ISO/IEC JTC1/SC1). Definitions of published parts of this vocabulary are identified by the symbol (I) after the definition; definitions taken from draft international standards, committee drafts, and working papers being developed by ISO/IEC JTC1/SC1 are identified by the symbol (T) after the definition, indicating that final agreement has not yet been reached among the participating National Bodies of SC1.
 
 
 
 
 
==Glossary Listing ==
 
Select a starting letter of glossary terms:
 
=== Glossary - A ===
 
A
 
'''ABIOS -'''Advanced BIOS. See ''BIOS''.
 
'''accumulator -'''(1) A register in which one operand of an operation can be stored and subsequently replaced by the result of that operation. (T) (2) In the IBM 3800 Printing Subsystem Models 3 and 8, a feature that supplies a separate storage that can hold data in raster form. It can be used either for composing a sheet of data that combines a large amount of variable and constant data, or for storing an electronic overlay in raster form that will be merged with variable data as the sheet is printed.
 
'''access permission -'''All access rights a user has regarding an object. (I)
 
'''adapter -'''A piece of hardware that modifies the system unit to allow it to operate in a particular way, often by connecting the system unit to an external device such as a video monitor.
 
'''adapter device driver -'''A device driver that provides hardware-dependent services for an ''OEM''adapter.
 
'''address space -'''(1) The range of addresses available to a program. (A) ( 2) The area of virtual storage available for a particular job.
 
'''all points addressable (APA) -'''In computer graphics, pertaining to the ability to address and display or not display each picture element (pel) on a display surface.
 
'''anchor block -'''An area of the internal resources of OS/2 Presentation Manager which is allocated to a process or thread that calls WinInitialize.
 
'''anchor point -'''The position or choice from which selection or deselection is extended.
 
'''APA -'''All points addressable.
 
'''API -'''Application programming interface.
 
'''application programming interface (API) -'''A functional interface supplied by the operating system, or by a separately-orderable licensed program, that allows an application program written in a high-level language to use specific data or functions of the operating system or the licensed program.
 
'''archive flag -'''In the OS/2 operating system, a flag of files and directories that the operating system uses to determine which files are new or modified. Files with this flag are included when a backup copy is made or when all the files are restored on a hard disk. See flag.
 
'''area -'''In computer graphics, a filled shape such as a solid rectangle.
 
'''ASCIIZ -'''A string of ASCII characters that is terminated with a byte containing the value 0.
 
'''aspect ratio -'''(1) The ratio of the height of a rectangle to its width. A rectangle of width 10 inches and height 5 inches has an aspect ratio of 10/ 5 or 2. (2) On a display screen, the ratio of the maximum length of a display line to the maximum length of a display column.
 
'''asynchronous (ASYNC) -'''(1) Pertaining to two or more processes that do not depend upon the occurrence of specific events such as common timing signals . (T) (2) Without regular time relationship; unexpected or unpredictable with respect to the execution of program instructions.
 
'''atom -'''A constant that represents a string. Once a string has been defined as an atom, the atom can be used in place of the string to save space. Strings are associated with their respective atoms in an ''atom table''. See ''integer atom''.
 
'''atom table -'''A table used to associate ''atom''s with the strings that they represent. This table contains the mechanism by which the presence of a string can be verified.
 
'''AVIO -'''Advanced Video Input/Output
 
 
 
 
 
=== Glossary - B ===
 
B
 
'''background color -'''The color assigned to a background image.
 
'''background mix -'''An attribute that determines how the background of a graphic primitive is combined with the existing color of the graphics presentation space.
 
'''base device driver -'''An OS/2 device driver that performs I/O during the OS/ 2 kernel boot sequence to provide IPL support. Base device drivers are loaded by way of the CONFIG.SYS BASEDEV keyword, rather than the DEVICE keyword. See ''BASEDEV keyword'', ''adapter device driver'', and ''device manager''.
 
'''BASEDEV keyword -'''New CONFIG.SYS keyword; loads a base device driver into the operating system.
 
'''Basic Input/Output System (BIOS) -'''Code that controls basic hardware operations, such as interactions with diskette drives, hard disk drives, and the keyboard.
 
'''Bezier curve -'''A mathematical technique of specifying a smooth, continuous line or surface, requiring a starting point and an ending point, with several intermediate points that influence or control the path of the linking curve.
 
'''BIOS -'''Basic Input/Output System.
 
'''bit-block transfer (bitblt) -'''Transfer of a rectangular array of bit-map data.
 
'''bitblt -'''Bit-block transfer.
 
'''bit map -'''A representation of an image by an array of bits.
 
'''block -'''(1) In programming languages, a compound statement that coincides with the scope of at least one of the declarations contained within it. A block may also specify storage allocation or segment programs for other purposes. (I) (2) A string of data elements recorded or transmitted as a unit. The elements may be characters, words or physical records. (T) (3) A collection of contiguous records recorded as a unit. Blocks are separated by interblock gaps and each block may contain one or more records. (A)
 
'''Bit block transfer (bitblt) -'''The process of transferring one or more blocks of data.
 
'''border -'''A visual indicator of a window's boundaries.
 
'''BPB -'''BIOS Parameter Block.
 
'''breakpoint -'''(1) A point in a computer program where execution may be halted. A breakpoint is usually at the beginning of an instruction where halts, caused by external intervention, are convenient for resuming execution. (T) (2) An instruction in a program for halting execution. Breakpoints are usually established at positions in a program where halts, caused by external intervention, are convenient for restarting. (T) (3) A place in a program, specified by a command or a condition, where the system halts execution and gives control to the workstation user or to a specified program.
 
'''Bus Master adapter -'''An adapter capable of performing Reads and Writes to physical storage by communicating directly with the storage subsystem ( memory) rather than depending on a host DMA channel or host CPU. Synonymous with ''first-party DMA adapter''.
 
 
 
 
 
=== Glossary - C ===
 
C
 
'''cached micro presentation space -'''A presentation space from a Presentation Manager owned store of micro presentation spaces. It can be used for drawing to a window only, and must be returned to the store when the task is complete.
 
'''CDB -'''Command Descriptor Block.
 
'''cell -'''See character cell.
 
'''character box -'''(1) An imaginary parallelogram on a display surface that contains all parts of one graphic character. Synonymous with bounding box. (T) (2) The maximum area in which a symbol and all associated elements, such as a cursor, an underline, or space surrounding the symbol to separate it from other symbols, can be printed or displayed. Synonymous with character cell. (3) The imaginary parallelogram whose boundaries govern the size, orientation, and spacing of individual characters to be displayed on a graphics display device.
 
'''character cell -'''(1) An addressable location on a display surface or printing medium. (2) The physical width and height in pels of a font. See also bounding box. (3) The imaginary box whose boundaries govern the size , orientation, and spacing of individual characters to be displayed on a workstation.
 
'''character mode -'''A mode that, in conjunction with the font type, determines the extent to which graphics characters are affected by the character box, shear, and angle attributes.
 
'''clipping -'''In computer graphics, removing those parts of display elements that lie outside of given boundary.
 
'''clip limits -'''The area of the paper that can be reached by a printer or plotter.
 
'''clipping path -'''A clipping boundary in world-coordinate space.
 
'''code page -'''An assignment of graphic characters and control function meanings to all code points; for example, assignment of characters and meanings to 256 code points for an 8-bit code, assignment of characters and meanings to 128 code points for a 7-bit code.
 
'''code point -'''A 1-byte code representing one of 256 potential characters.
 
'''code segment -'''An executable section of programming code within a load module.
 
'''color conversion -'''Changing one color format to another. Required, for example, when the source color format is different from the destination color format. When going from the monochrome color format to the color format, 1 (one) bits are converted to the image foreground color, and 0 ( zero) bits are converted to the image background color.
 
When going from color to monochrome, all pels that match the passed background color are converted to the image background color of the destination.
 
All other pels are converted to the image foreground color of the destination. The color conversion takes place prior to any mix mode.
 
'''color dithering -'''See dithering.
 
'''command code -'''In this specification, refers to a group of related commands that an adapter device driver can receive.
 
All command codes have a prefix of &quot;IOCC_&quot;. For example, common I/O requests (such as Read, Write, etc.) are grouped under the command code IOCC_EXECUTE_IO.
 
'''command data block -'''A data structure defined by the Small Computer System Interface standard to send commands to devices that conform to SCSI standards.
 
'''command descriptor block (CDB) -'''The structure used to communicate commands from a source to a destination.
 
'''command modifier -'''In this specification, a specific operation that an adapter device driver is to perform.
 
All command modifiers have a prefix of &quot;IOCM_&quot;. For example, an adapter device driver might receive an IOCC_EXECUTE_IO command with a command modifier of IOCM_READ.
 
'''compatibility kernel -'''The portion of the OS/2 kernel that exists to support DOS INT 20, 21, 25, 26, and 27 functions. It acts as an interface to common kernel functionality such as the file system.
 
'''CON -'''Character-device name reserved for the console keyboard and screen.
 
'''conditional compilation -'''Processing by the preprocessor of certain specified code in the file, depending on the evaluation of a specified condition.
 
'''context hook -'''Similar to a &quot;force flag&quot; in earlier versions of OS/2. These are events, signaled by a virtual device driver, that are processed at task time. Forcing an IRET, and simulating an NMI, can fall into this category.
 
'''control program -'''A computer program designed to schedule and to supervise the execution of programs of a computer system.
 
'''controller sector buffer -'''One or more buffers, managed by a hardware adapter, to improve I/O transfer rates by helping to match a device and software timing requirements.
 
 
 
 
 
=== Glossary - D ===
 
D
 
'''DASD -'''Direct-access storage device.
 
'''data bus -'''A bus used to communicate data internally and externally to and from a processing unit, storage, and peripheral devices. (A) See bus.
 
'''data structure -'''The syntactic structure of symbolic expressions and their storage allocation characteristics. (T)
 
'''DBCS -'''Double-byte character set.
 
'''DC -'''Device context.
 
'''DDB -'''Device-dependent bit map.
 
'''deinstantiation -'''See ''instantiation''.
 
'''DevHlp -'''Device helper.
 
'''device context (DC) -'''A logical description of a data destination such as memory, metafile, display, printer, or plotter. See also ''direct device context, information device context, memory device context, metafile device context, and screen device context''.
 
'''device driver -'''A file that contains the code needed to attach and use a device such as a display, printer, or plotter.
 
'''device driver initialization (init) time -'''See ''initialization (init) time, device driver''.
 
'''device driver profile -'''A file with a &quot;DDP&quot; extension, containing a script that is interpreted by the OS/2 DDINSTAL utility. Among other things, it defines which files to copy from installation diskettes to target directories and specifies how the CONFIG.SYS file will be updated.
 
'''device helper (DevHlp) -'''(1) A kernel service (memory, hardware interrupt, software interrupt, queuing, semaphore, and so forth) provided to physical device drivers. (2) A callable C-language or assembler-language routine that provides an operating system service for an OS/2 device driver.
 
'''device object -'''A device that provides a means of communication between a computer and the outside world. A printer is an example of a device object.
 
'''device table -'''A data structure containing a summary of the adapters an adapter device driver supports and a list of the I/O devices attached to each adapter. This data structure is built by the adapter device driver in response to an IOCC_CONFIGURATION IOCM_GET_DEVICE_TABLE request.
 
'''direct access storage device (DASD) -'''A device in which access time is effectively independent of the location of the data.
 
'''direct memory access (DMA) -'''(1) A technique for moving data directly between main storage and peripheral equipment without requiring processing of the data by the processing unit. (2) The transfer of data between memory and input/output units without processor intervention.
 
'''display frame -'''(1) In computer graphics, an area in storage in which a display image can be recorded. (2) In computer micrographics, an area on a microform in which a display image can be recorded.
 
'''dispatch table -'''(1) A block of memory, allocated by the graphics engine, for the containment of entry points for use by a display driver. (2) An array of pointers to function-handling routines.
 
'''dithering -'''A technique for interleaving dark and light pels so that the resulting image looks smoothly shaded from a distance.
 
'''DLL -'''Dynamic link library.
 
'''DMA -'''Direct memory access.
 
'''double-byte character set (DBCS) -'''A set of characters in which each character is represented by two bytes. Languages such as Japanese, Chinese, and Korean, which contain more characters than can be represented by 256 code points, require double-byte character sets. Because each character requires 2 bytes, the typing, display, and printing of DBCS characters requires hardware and programs that support DBCS. Contrast with single-byte character set.
 
'''driver -'''(1) A program (and possibly data files) that contain information needed to run a particular unit, such as a plotter, printer, port, or mouse. See also device driver and printer driver. (2) A system or device that enables a functional unit to operate.
 
'''dynamic link library (DLL) -'''A file containing executable code and data bound to a program at load time or run time, rather than during linking. The code and data in a dynamic link library can be shared by several applications simultaneously.
 
 
 
 
 
=== Glossary - E ===
 
E
 
'''entry point -'''(1) In a database, the record that is first accessed upon entry into a database, caused by a user's command. (T) (2) The address or label of the first instruction executed on entering a computer program, routine, or subroutine. A computer program, routine, or subroutine may have a number of different entry points, each perhaps corresponding to a different function or purpose. (I) (A) Synonymous with entrance, entry. (3) In a routine, any place to which control can be passed. (A) (4) In the C, FORTRAN, and Pascal languages, the address or label of the first instruction processed or entered in a program, routine, or subroutine. A program, routine, or subroutine can have a number of different entry points , each corresponding to a different function or purpose.
 
'''EOI -'''End Of Interrupt
 
 
 
 
 
=== Glossary - F ===
 
F
 
'''Far call -'''Code that calls from one segment into another segment.
 
'''fillet -'''An arc that is tangential to the end points of two adjacent lines. See also ''polyfillet''.
 
'''filter adapter device driver -'''A special class of adapter device drivers that do not manage the hardware directly, but monitor the stream of commands between a device manager and an adapter device driver. See ''Device Manager''and ''adapter device driver''.
 
'''first-party DMA adapter -'''See ''bus master adapter''.
 
'''flag -'''A characteristic of a file or directory that enables it to be used in certain ways. See also ''archive flag'', ''hidden flag'', and ''read-only flag''.
 
'''flat address -'''See ''linear address''.
 
'''frame styles -'''Standard window layouts provided by the Presentation Manager .
 
'''freeze and thaw services -'''Functions that prevent a DOS session from executing (VDHFreezeVDM) until the matching thaw function (VDHThawVDM) is called. The freeze occurs when the specified DOS session leaves ''kernel mode'' .
 
 
 
 
 
=== Glossary - G ===
 
G
 
'''GDT -'''Global descriptor table.
 
'''Global Descriptor Table (GDT) -'''A table that defines code and data segments available to all tasks in an application.
 
'''glyph -'''A graphic symbol whose appearance conveys information; for example, the vertical and horizontal arrows on cursor keys that indicate the directions in which they control cursor movement, the sunburst symbol on the screen illumination control of a display device.
 
'''GPI -'''Graphics programming interface
 
'''graphic primitive -'''In computer graphics, a basic element, such as an arc or a line, that is not made up of smaller parts and that is used to create diagrams and pictures.
 
'''graphics attributes -'''The attributes that apply to graphics primitives. Examples are color selection, line type, and shading pattern definition. Contrast with segment attributes.
 
'''Graphics programming interface (GPI) -'''The formally-defined programming language that lies between an IBM graphics program and the user of the program.
 
'''graphics segment -'''A sequence of related graphic primitives and graphics attributes. See also ''graphic primitive''.
 
'''GRE -'''Graphics engine.
 
 
 
 
 
=== Glossary - H ===
 
H
 
'''handle -'''(1) An identifier that represents an object, such as a device or a window, to the Presentation Interface. (2) In the Advanced DOS and OS/2 operating systems, a binary value created by the system that identifies a drive, directory, and file so that the file can be found and opened.
 
'''handshaking -'''A method by which two pieces of hardware, such as a personal computer and a plotter, can communicate. Depending upon the devices communicating, handshaking occurs either as a hardware function or through software, such as a device driver.
 
'''hard error -'''An error condition on a network that requires that the network be reconfigured or that the source of the error be removed before the network can resume reliable operation.
 
'''hardware palette -'''The array of RGBs that the physical device is displaying .
 
'''heap -'''An area of free storage available for dynamic allocation by an application. Its size varies depending on the storage requirements of the application.
 
'''hex -'''See hexadecimal
 
'''hexadecimal -'''Pertaining to a system of numbers to the base 16; hexadecimal digits range from 0 through 9 and A through F, where A represents 10 and F represents 15.
 
'''hook -'''A point in a system-defined function where an application can supply additional code that the system processes as though it were part of the function.
 
'''hook chain -'''A sequence of hook procedures that are &quot;chained&quot; together so that each event is passed in turn to each procedure in the chain.
 
 
 
 
 
=== Glossary - I ===
 
I
 
'''IDC -'''Inter-device-driver communication.
 
'''in-memory buffer -'''A block of memory in the address space of the host machine, used for data transfer.
 
'''init time -'''See initialization time, device driver.
 
'''initialization time, device driver -'''After the OS/2 loads a device driver, it sends it an OS/2 request packet to initialize. During this initialization, certain DevHlp functions are not permitted. Also called init time.
 
'''Input/Output Control (IOCtl) -'''A system service that provides a way for an application to send device-specific control commands to a device driver.
 
'''Input/Output Privilege Level (IOPL) -'''Allows part of a Ring 3 application or device driver to execute at Ring 0.
 
'''input router -'''OS/2 internal process that removes messages from the system queue.
 
'''inter-device-driver communication (IDC) -'''A mechanism that enables a physical device driver to communicate with another physical device driver.
 
'''interprocess communication -'''In the OS/2 operating system, the exchange of information between processes or threads through semaphores, queues, and shared memory.
 
'''interrupt -'''An instruction that directs the microprocessor to suspend what it is doing and run a specified routine. When the routine is complete, the microprocessor resumes its original work. See also routine.
 
'''interrupt request (IR) -'''Broadly, an &quot;interrupt request level&quot;, referring to pending or in-service interrupt requests, or to a specific level (for example, IR 4).
 
'''interrupt request flag -'''A bit in the 8259 PIC controller that indicates an interrupt is pending on particular level. The VPIC also maintains a virtual interrupt request flag for each interrupt level for each DOS session.
 
'''interrupt service flag -'''A bit in the 8259 PIC controller that indicates an interrupt request is being serviced. It is cleared when the PIC is sent EOI . The VPIC maintains a virtual interrupt service flag indicating that a simulated interrupt is in-progress in a DOS session.
 
'''interrupt time -'''When a device driver is run because of an interrupt rather than because of an application request. OS/2 device drivers receive interrupts either from the hardware they manage or from the system real- time clock.
 
During interrupt time, certain DevHlp functions are not permitted. Also, addresses received directly from OS/2 applications might not be valid unless they are converted system addresses.
 
'''IOCtl -'''Input/Output Control.
 
'''IOPL -'''Input/Output Privilege Level.
 
'''IORB -'''Input/Output Request Block.
 
'''Input/Output Request Block (IORB) -'''A data structure defined by this specification that is passed as a parameter on all calls to an adapter device driver. It contains a fixed section, followed by a command-dependent section.
 
'''IORBH -'''Input/Output Request Block Header
 
'''IRET -'''Interrupt return.
 
'''IRQ -'''Interrupt Request.
 
 
 
 
 
=== Glossary - J ===
 
J
 
'''journal -'''A special-purpose file or data set that can be used to provide an audit trail of operator and system actions, or as a means of recovering superseded data.
 
 
 
 
 
=== Glossary - K ===
 
K
 
'''kanji -'''A graphic character set consisting of symbols used in Japanese ideographic alphabets. Each character is represented by 2 bytes.
 
'''kernel -'''(1) The part of an operating system that performs basic functions such as allocating hardware resources. (2) A program that can run under different operating system environments.
 
'''kerning -'''The design of graphic characters so that their character boxes overlap. The toned picture elements (pels) of the character appear outside the character cell.
 
'''Note:'''Kerning allows character boxes to overlap and characters to run together, so that characters can be designed for cursive languages, ligatures, or any other kind of character that requires more than one character box. It also allows for design of proportional-spaced fonts. By overlapping character boxes, characters can be placed closer together, or they can be placed farther apart by using overlapped blank character boxes.
 
 
 
 
 
=== Glossary - L ===
 
L
 
'''LCT -'''logical color table.
 
'''LDT -'''Local descriptor table.
 
'''LIFO stack -'''A data structure from which data is retrieved in &quot;Last-In, First-Out&quot; order.
 
'''linked list -'''A list in which the data elements may be dispersed, but in which each data element contains information for locating the next. Synonym for chained list.
 
'''linear address -'''A unique value that identifies the memory object.
 
'''Local Descriptor Table (LDT) -'''A table that defines code and data segments specific to a single task.
 
'''logical palette -'''An array of RGB and mapping index pairs, created by the device driver when defining a palette (as a result of a GpqCreatePalette call).
 
'''LVB -'''Logical Video Buffer.
 
 
 
 
 
=== Glossary - M ===
 
M
 
'''memory device context -'''A logical description of a data destination that is a memory bit map. See also device context.
 
'''metafile -'''A file containing a series of attributes that set color, shape, and size, usually of a picture or a drawing. Using a program that can interpret these attributes, a user can view the assembled image.
 
'''metafile device context -'''A logical description of a data destination that is a metafile which is used for graphics interchange. See also device context.
 
'''mickey -'''A unit of measurement for physical mouse motion whose value depends on the mouse device driver that is currently loaded.
 
'''mixed character string -'''A string containing a mixture of one-byte and kanji or Hangeul (two-byte) characters.
 
'''mutex semaphore -'''(Mutual exclusion semaphore). A semaphore that enables threads to serialize their access to resources. Only the thread that currently owns the mutex semaphore can gain access to the resource, thus preventing one thread from interrupting operations being performed by another.
 
 
 
 
 
=== Glossary - N ===
 
N
 
'''named pipe -'''A named buffer that provides client-to-server, server-to- client or duplex communication between unrelated processes. Contrast with unnamed pipe.
 
'''notification callout -'''The feature that provides for a routine to be called on completion of an input/output request. See also notification routine.
 
'''notification routine -'''The routine indicated in an input/output request block to be called on completion of that request. See also notification callout.
 
'''null-terminated string -'''A string of (n+1) characters where the (n+1)th character is the &quot;null&quot; character (X'00') and is used to represent an n- character string with implicit length. Also called a &quot;zero-terminated&quot; string or an &quot;ASCIIZ&quot;. string.
 
 
 
 
 
=== Glossary - O ===
 
O
 
 
 
 
 
=== Glossary - P ===
 
P
 
'''palette -'''A list of colors assigned to various areas on a panel. A user can change the color of these areas.
 
'''PDD -'''Physical Device Driver.
 
'''PDE -'''PageDirectoryEntry.
 
'''pel -'''Picture element.
 
'''permissible action -'''In a conceptual schema language, an action conforming to specified rules or constraints that changes a presumably consistent collection of sentences into a consistent one or makes known a consistent one present in the information base or conceptual schema.
 
'''phase alignment -'''Aligning source bits with destination bits. Often required in a Bitblt function move operation where byte blocks are moved on bit boundaries.
 
'''physical address -'''A 32-bit byte address giving the actual address in physical storage for a data item.
 
'''physical device driver (PDD) -'''A system interface that handles hardware interrupts and supports a set of input and output functions.
 
'''pipe -'''See named pipe, unnamed pipe.
 
'''picture element (pel, pixel) -'''(1) In computer graphics, the smallest element of a display surface that can be independently assigned color and intensity. (T) . (2) The area of the finest detail that can be reproduced effectively on the recording medium. (3) An element of a raster pattern about which a toned area on a photoconductor can appear.
 
'''PIO -'''Programmed I/O.
 
'''pixel -'''Picture element.
 
'''polyfillet -'''A curve based on a sequence of lines. The curve is tangential to the end points of the first and last lines, and tangential also to the midpoints of all other lines.
 
'''polyline -'''In computer graphics, a sequence of adjoining lines.
 
'''pop -'''To remove an item from the top of a pushdown list. Contrast with push .
 
'''prefetch -'''To locate and load a quantity of data in anticipation of a request.
 
'''presence-check function -'''A Ring 3 (non-privileged) .EXE program that determines whether a given hardware interface is present on a workstation.
 
'''PRESENCECHECK -'''A keyword, interpreted by the DDINSTAL utility, to determine whether to process the device driver profile file, based on the return code from PRESENCECHECK.
 
'''printer driver -'''A file that describes the physical characteristics of a printer, plotter, or other peripheral device, and is used to convert graphics and text into device-specific data at the time of printing or plotting.
 
'''Print Manager -'''In the Presentation Manager, the part of the spooler that manages the spooling process. It also allows the user to view print queues and to manipulate print jobs.
 
'''privilege level -'''A method of protection that allows only certain program instructions to be used by certain programs.
 
'''program group -'''Several programs that can be acted upon as a single entity.
 
'''protect mode -'''A method of program operation that limits or prevents access to certain instructions or areas of storage. Contrast with real mode.
 
'''push -'''To add an item to the top of a pushdown list. Contrast with pop.
 
 
 
 
 
=== Glossary - Q ===
 
Q
 
'''queued device context -'''A logical description of a data destination (for example, a printer or plotter) where the output is to go through the spooler. See also device context.
 
 
 
 
 
=== Glossary - R ===
 
R
 
'''read-only memory basic input/output system (ROM-BIOS) -'''Microcode in read- only memory that controls basic input/output operations such as interactions with cassettes, diskette drives, hard disk drives, and the keyboard. See also BIOS, NetBIOS.
 
'''Note:'''ROM BIOS allows the user to write programs and add or remove devices without concern for characteristics such as device addresses.
 
'''real mode -'''In the OS/2 operating system, a method of program operation that does not limit or prevent access to any instructions or areas of storage. The operating system loads the entire program into storage and gives the program access to all system resources.
 
'''reentrant -'''The attribute of a program or routine that allows the same copy of the program or routine to be used concurrently by two or more tasks.
 
'''removable-media indicator -'''A flag (bit) indicating that a device permits media removal.
 
'''resource -'''The means of providing extra information used in the definition of a window. A resource can contain definitions of fonts, templates, accelerators and mnemonics; the definitions are held in a resource file.
 
'''resurrection -'''The Presentation Manager event that occurs when switched back from a full-screen DOS or WIN-OS/2 session.
 
'''RETF -'''Return far.
 
'''reverse video -'''A form of highlighting a character, field, or cursor by reversing the color of the character, field, or cursor with its background; for example, changing a red character on a black background to a black character on a red background.
 
'''ROM BIOS -'''Read-Only Memory Basic Input/Output System.
 
'''ROP -'''Raster operation.
 
'''RTC -'''Real-Time Clock.
 
 
 
 
 
=== Glossary - S ===
 
S
 
'''SBCS -'''Single-byte character set
 
'''SCB -'''See subsystem control block architecture.
 
'''screen device context -'''A logical description of a data destination that is a particular window on the screen. See also device context.
 
'''SCSI -'''Small Computer System Interface.
 
'''seamless windows -'''An architecture contained within OS/2 which permits one or more applications to share windowed desktop graphical space and other resources, while executing concurrently. Application session windows managed by seamless windows can share border information, and pointing device transitions from session to session are handled smoothly and transparently.
 
'''second-party DMA adapter -'''See DMA slave.
 
'''semaphore -'''(1) A variable that is used to enforce mutual exclusion. (T) (2) An indicator used to control access to a file; for example, in a multiuser application, a flag that prevents simultaneous access to a file. (3) An entity used to control access to system resources. Processes can be locked to a resource with semaphores if the processes follow certain programming conventions.
 
'''sense data -'''Data which describes an I/O error as defined by the ANSI SCSI specifications.
 
'''single-byte character set (SBCS) -'''A character set in which each character is represented by a one-byte code. Contrast with double-byte character set.
 
'''Small Computer System Interface (SCSI) -'''An input and output bus that provides a standard interface between the OS/2 multimedia system and peripheral devices.
 
'''spline curve -'''In computer graphics, a shape created when a user specifies a series of points and the computer software draws a curve that smoothly approaches those points.
 
'''spooler -'''A program that intercepts data going to a device driver and writes it to a disk. The data is later printed or plotted when the required device is available. A spooler prevents output from different sources from being intermixed.
 
'''synchronous -'''Pertaining to two or more processes that depend upon the occurrence of specific events such as common timing signals.
 
 
 
 
 
=== Glossary - T ===
 
T
 
'''text window -'''See VIO window.
 
'''thread -'''The smallest unit of operation to be performed within a process.
 
'''thunk -'''term used to describe the process of address conversion, stack, and structure realignment that is necessary when passing control between 16-bit and 32-bit modules.
 
'''thunk layer -'''An interface that converts 32-bit parameters to 16-bit parameters, and maps linear addresses to segmented addresses.
 
'''time slice -'''(1) The period of processing time allocated for running a program. (2) An interval of time on the processing unit allocated for use in performing a task. After the interval has expired, processing unit time is allocated to another task, so a task cannot monopolize processing unit time beyond a fixed limit.
 
'''tuple -'''In a relational database, a part of a relation that uniquely describes an entity and its attribute.
 
 
 
 
 
=== Glossary - U ===
 
U
 
'''unnamed pipe -'''A circular buffer created in memory; used by related processes to communicate with one another. Contrast with named pipe.
 
 
 
 
 
=== Glossary - V ===
 
V
 
'''VBIOS -'''Virtual BIOS device driver
 
'''VCMOS -'''Virtual CMOS device driver
 
'''VDD -'''Virtual device driver
 
'''VDH -'''Virtual video Device Handler
 
'''VDM -'''Virtual DOS Machine; use DOS session.
 
'''VDMA -'''Virtual Direct Memory Access device driver
 
'''VDSK -'''Virtual hard DiSK device driver
 
'''video graphics adapter (VGA) -'''A computer adapter that provides high- resolution graphics and a total of 256 colors.
 
'''VIO -'''Virtual Input/Output
 
'''VIRR -'''Virtual Interrupt Request Register
 
'''Virtual Device Driver (VDD) -'''In the OS/2 operating system, a type of device driver used by DOS programs running in a DOS session to access devices, such as the screen or mouse, which must be shared with other processes in the system. The virtual device driver maps DOS device commands to the normal (physical) device driver under OS/2 2.0 and later versions of the operating system.
 
'''virtual DevHlp (VDH) -'''Kernel (linear memory, paging, hardware interrupt, event control, port control) services provided to virtual device drivers.
 
'''virtual I/O (VIO) -'''A facility that pages data into and out of external page storage.
 
'''virtual memory -'''Synonym for virtual storage.
 
'''Virtual Programmable Interrupt Controller -'''Virtualizes the 8259 Programmable Interrupt Controller (PIC). A special virtual device driver, in that it provides services to other virtual device drivers.
 
'''virtual storage -'''Addressable space that is apparent to the user as the processor storage space, from which the instructions and the data are mapped into the processor storage locations. Synonymous with virtual memory .
 
'''visible region -'''A window's presentation space clipped to the boundary of the window and the boundaries of any overlying window.
 
'''VPIC -'''Virtual Programmable Interrupt Controller device driver.
 
'''VRAM -'''Video Random-Access Memory.
 
'''VTIMER -'''Virtual TIMER device driver.
 
'''V86 mode -'''Virtual 8086 mode of the 80386 CPU.
 
 
 
 
 
=== Glossary - W ===
 
W
 
'''window coordinates -'''A set of coordinates by which a window position or size is defined; measured in device units, or ''pels''.
 
 
 
 
 
=== Glossary - X ===
 
X
 
 
 
 
 
=== Glossary - Y ===
 
Y
 
There are no glossary terms for this initial letter.
 
 
 
 
 
=== Glossary - Z ===
 
Z
 
 
'''Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation'''
 
[[Category:Driver Articles]]

Latest revision as of 04:44, 29 September 2022

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Virtual Device Driver Reference for OS/2
Part 1. Overview
Introduction
Virtual Device Driver Architecture and Operations

Part 2. Virtual Device Drivers

Base Virtual Device Drivers
Installable Virtual Device Drivers
Virtual Mouse Device Driver

Part 3. Reference Material

C Language Virtual DevHlp Services

Appendixes

OS/2 Version Compatibility Considerations
Assembler Language Syntax
Notices
Glossary

EDM/2 preamble

This is the Virtual Device Driver Reference for OS/2 as last published by IBM in 1995. It is republished here with explicit permission from the company (Copyright Permission #21953) and you should keep in mind that it is an intellectual property of International Business Machines Corp. that cannot be changed or reused without their permission and is not governed by the Attribution-Share Alike 3.0 licence like the rest of the EDM/2 Wiki.

The content of the documentation is unchanged apart from the following:

  • The original document was an INF file split into thousands of different small sections, these have been consolidated into chapters, and restructured to fit HTML formatting, mimicking the original GML format as much as possible.
  • Sales, technical help, download and contact information has been removed. The VDDR/2 and the related SDK's are no longer for sale, nor is support available from IBM. Some of the INF viewer related help has been removed as well as it is superfluous after the format change and might be misleading, and the Glossary and Notices section was merged with other DDK/SDK glossary sections as they are all identical.
  • Miniscule changes have been made to the text, spelling errors, formatting errors and possible copy and paste errors have been fixed and/or noted.

Outside of formatting changes, adding Wikilinks and graphic improvements, the document shall be left as it is. It should be noted that the some of the driver models and data formats described in the documentation are have been replaced or extended by both IBM and third parties, but that does not mean that this document should be changed, but it is acceptable that a link is created to an internal or external article that explains the newer models and formats.

About This Book

The OS/2 Virtual Device Driver Reference defines what a virtual device driver is, how it operates, and when to use one. In addition, a description of the types of virtual device drivers, their interfaces, and the available kernel services is provided. System and application programmers can use the information found in this book to write their own virtual device drivers and subsystems.

Knowledge of a programming language (such as C or assembler) that is used for writing OS/2 applications is necessary, and the programmer must be familiar with the workings of the OS/2 operating system.

How This Book is Organized

This book consists of three parts:

Part 1. Overview

Introduction
This chapter contains a general description of the three types of OS/2 device drivers, and an overview of the virtual device driver mechanism and kernel services.
Virtual Device Driver Architecture and Operations
This chapter contains a description of virtual device driver architecture, operations, and communication between device drivers.

Part 2. Virtual Device Drivers

Base Virtual Device Drivers
This chapter contains a description of each base virtual device driver shipped with OS/2.
Installable Virtual Device Drivers
This chapter contains a description of each installable virtual virtual device driver shipped with OS/2.
Virtual Mouse Device Driver
This chapter describes the virtual mouse device driver (VMOUSE), which is responsible for all mouse support in multiple DOS sessions.

Part 3. Reference Material

C Language Virtual DevHlp Services
This chapter contains full C language descriptions of the kernel functions available to virtual device drivers.

Appendixes

OS/2 Version Compatibility Considerations
This table describes information added to or changed since the availability of OS/2 Warp, Version 3 in terms of version compatibility.
Assembler Language Syntax
This appendix contains assembler language versions of the kernel functions covered in Chapter 6.
Notices
This appendix contains legal notices and lists the trademarks of the IBM Corporation and trademarks of other companies.

A glossary and an index are included at the back of this book.

Introduction

Virtual device drivers are used by the OS/2* operating system to act as virtual devices for DOS applications executing in a DOS session. These device drivers provide virtual hardware support for DOS and DOS applications.

The virtual device drivers shipped with OS/2 will virtualize most of the standard devices, including:

  • Asynchronous Communication (RS-232C)
  • DMA (Direct Memory Access)
  • Fixed Disk and Diskette
  • Keyboard
  • Mouse
  • Parallel Port Printer
  • PIC (Programmable Interrupt Controller)
  • Timer
  • Video

This book provides an overview of the virtual device driver mechanism and the available kernel services.

Types of OS/2 Device Drivers

Three types of device drivers are used in the OS/2 operating system:

  • Virtual device drivers
  • Physical device drivers
  • Presentation drivers

Virtual Device Drivers

The virtual device driver is an installable module, responsible for virtualizing a particular piece of hardware and associated ROM BIOS in the manner expected by a DOS application. This device driver achieves virtualization by emulating I/O port and device memory operations. Virtual device drivers are 32-bit device drivers, operating at Ring 0, the most privileged level of the operating system. To achieve a certain level of hardware independence, a virtual device driver usually communicates with a physical device driver in order to interact with hardware.

Physical Device Drivers

Standard I/O devices are supported by base physical device drivers that are part of the OS/2 operating system. Additional or replacement physical device drivers can be loaded to extend the control provided by the base device drivers, or to support nonstandard I/O devices. Typical examples of these loadable device drivers are ANSI.SYS and ANSI.DLL, which are loaded by "DEVICE=" statements in the CONFIG.SYS file, and provide additional functions on the interfaces to the screen and keyboard. Physical device drivers are initialized at Ring 3 and operate at Ring 0.

Further information on physical device drivers, physical device driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the OS/2 Physical Device Driver Reference.

Presentation Drivers

The Presentation Manager* I/O interface for output devices is a high-level interface. This interface is similar to the API (Application Programming Interface) call interface, which uses the program stack to communicate with , or pass parameters to, the presentation drivers. These drivers are special-purpose I/O routines operating with I/O privilege at privilege level 2 (Ring 2) or privilege level 3 (Ring 3). Their main function is to process function calls made by the Presentation Manager interface on behalf of Presentation Manager applications. Hardcopy presentation drivers communicate with OS/2 device drivers through the file system emulation functions. Display presentation drivers interface directly with the hardware.

Presentation drivers are dynamic link library modules that are supplied as files and are identified by the extension ".DRV". When the Presentation Manager is initialized, the display presentation driver is automatically loaded and enabled. Other presentation drivers (for example, the hardcopy presentation drivers) are loaded and enabled when an application calls the DevOpenDC function to open the device.

Presentation drivers service requests only from applications running in Presentation Manager sessions in the OS/2 mode. Output data and requests for information are passed to the presentation driver as function calls to the presentation driver interface. The definition of the call interface is given in terms of the codes and data passed to the presentation driver interface through the program stack.

Include (.INC and .h) files are shipped with the Developer's Toolkit for OS /2 to provide support for building presentation drivers that are written in either C or assembler language. These files contain function prototypes, defined values, and data structures used by the various functions.

Further information on presentation drivers, presentation driver interfaces (including detailed descriptions of the calling conventions), and the system services available to these drivers is found in the OS/2 Presentation Device Driver Reference.

When to Use a Virtual Device Driver

The device virtualization provided by OS/2 can be extended by creating a virtual device driver (VDD) and the corresponding physical device driver (PDD). A user-supplied virtual device driver virtualizes the hardware interfaces of an option adapter or device, usually to migrate an existing DOS application into the OS/2 DOS environment.

Note that a virtual device driver is needed only in a limited number of cases. If there is no requirement for multiple sessions to share access to a device, a requirement for a virtual device driver is unlikely. OS/2 maps interrupts, I/O ports, and I/O memory directly to any DOS device driver or DOS application which attempts to access these resources. As long as a resource is not already claimed by another session or by the OS/2 kernel, it is directly accessible to the DOS program.

Where access-sharing is required, it is generally not necessary to create a virtual device driver if the I/O is handle-based. DOS INT 21h I/O requests are routed by the OS/2 file system to the protect-mode physical device driver. If all I/O is handle-based, it is necessary only to create the physical device driver.

For block devices, it is recommended that OS/2 support be provided only by a physical device driver. Both DOS and OS/2 sessions will then access the device through file system interfaces defined by DOS and the OS/2 operating system.

In the absence of a sharing requirement, a virtual device driver might be necessary if the device has strict interrupt service latency requirements. A virtual device driver/physical device driver pair improves the interrupt service latency for an option adapter or device.

OS/2 Version Compatibility Considerations

The following table lists information that has been added to or changed in this documentation since the availability of OS/2 Warp, Version 3. When writing a device driver, you will want to take into consideration these particular changes, which may affect the downward compatibility of these items.

Item Added or Changed Date Item Added or Changed Compatibility of Addition or Change
Advanced OS/2 Joystick Device Driver November 1995 OS/2 Warp, Version 3 and higher
Retrieved from "https://www.edm2.com/index.php?title=Virtual_Device_Driver_Reference_for_OS/2&oldid=78604"