Jump to content

VDDR/2 - C Language Virtual DevHlp Services: Difference between revisions

From EDM2
Newer edit →
 
No edit summary
Line 1: Line 1:
#REDIRECT [[Virtual Device Driver Reference for OS/2:C Language Virtual DevHlp Services]]
 
 
 
 
=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>

Revision as of 04:12, 8 May 2016



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
VDHAllocBlockbyte-granular memory management service
VDHAllocDMABufferDMA service
VDHAllocDOSMembyte-granular memory management service
VDHAllocHookhook management service
VDHAllocMembyte-granular memory management service
VDHAllocPagespage-granular memory management service
VDHArmBPHookhook management service
VDHArmContextHookhook management service
VDHArmReturnHookhook management service
VDHArmSTIHookhook management service
VDHArmTimerHooktimer service
VDHArmVPMBPHookDPMI service
VDHBeginUseVPMStackDPMI service
VDHCallOutDMADMA service
VDHChangeVPMIFDPMI service
VDHCheckPagePermDPMI service
VDHCheckVPMIntVectorDPMI service
VDHClearVIRRVirtual interrupt service
VDHClosefile or device I/O service
VDHCloseVDDinter-device communication service
VDHCloseVIRQVirtual interrupt service
VDHCopyMembyte-granular memory management service
VDHCreateBlockPoolbyte-granular memory management service
VDHCreateSelGDT selector service
VDHCreateSemsemaphore service
VDHDecodePropertyDOS settings service
VDHDestroyBlockPoolbyte-granular memory management service
VDHDestroySelGDT selector service
VDHDestroySemsemaphore service
VDHDevBeepmiscellaneous virtual DevHlp service
VDHDevIOCtlfile or device I/O service
VDHDisarmTimerHooktimer service
VDHEndUseVPMStackDPMI service
VDHEnumerateVDMsmiscellaneous virtual DevHlp service
VDHExchangeMembyte-granular memory management service
VDHFindFreePagespage-granular memory management service
VDHFreeBlockbyte-granular memory management service
VDHFreeDMABufferDMA service
VDHFreeHookhook management service
VDHFreeMembyte-granular memory management service
VDHFreePagespage-granular memory management service
VDHFreezeVDMDOS session control service
VDHGetCodePageFontmiscellaneous virtual DevHlp service
VDHGetDirtyPageInfopage-granular memory management service
VDHGetErrormiscellaneous virtual DevHlp service
VDHGetFlagsmiscellaneous virtual DevHlp service
VDHGetSelBaseDPMI service
VDHGetVPMExceptDPMI service
VDHGetVPMIntVectorDPMI service
VDHHaltSystemDOS session control service
VDHHandleFromPIDmiscellaneous virtual DevHlp service
VDHHandleFromSGIDmiscellaneous virtual DevHlp service
VDHInstallFaultHookpage-granular memory management service
VDHInstallIntHookhook management service
VDHInstallIOHookhook management service
VDHInstallUserHookhook management service
VDHIsVDMFrozenDOS session control service
VDHKillVDMDOS session control service
VDHLockMemmemory-locking memory management service
VDHMapPagespage-granular memory management service
VDHOpenfile or device I/O service
VDHOpenPDDinter-device communication service
VDHOpenVDDinter-device communication service
VDHOpenVIRQVirtual interrupt service
VDHPhysicalDiskfile or device I/O service
VDHPopIntV8086 stack manipulation service
VDHPopRegsV8086 stack manipulation service
VDHPopStackV8086 stack manipulation service
VDHPopupmiscellaneous virtual DevHlp service
VDHPostEventSemsemaphore service
VDHPrintCloseparallel port and printer service
VDHPushFarCallV8086 stack manipulation service
VDHPushIntV8086 stack manipulation service
VDHPushRegsV8086 stack manipulation service
VDHPushStackV8086 stack manipulation service
VDHPutSysValuemiscellaneous virtual DevHlp service
VDHQueryFreePagespage-granular memory management service
VDHQueryHookDatahook management service
VDHQueryLinmiscellaneous virtual DevHlp service
VDHQueryKeyShiftkeyboard service
VDHQueryPropertyDOS settings service
VDHQuerySelGDT selector service
VDHQuerySemsemaphore service
VDHQuerySysValuemiscellaneous virtual DevHlp service
VDHQueryVIRQVirtual interrupt service
VDHRaiseExceptionDPMI service
VDHReadfile or device I/O service
VDHReadUBufDPMI service
VDHReallocPagespage-granular memory management service
VDHRegisterAPIRegister API handler
VDHRegisterDMAChannelDMA service
VDHRegisterPropertyDOS settings service
VDHRegisterVDDinter-device communication service
VDHReleaseCodePageFontmiscellaneous virtual DevHlp service
VDHReleaseMutexSemsemaphore service
VDHRemoveFaultHookpage-granular memory management service
VDHRemoveIOHookhook management service
VDHReportPeekidle DOS application management service
VDHRequestMutexSemsemaphore service
VDHRequestVDDinter-device communication service
VDHReservePagespage-granular memory management service
VDHResetEventSemsemaphore service
VDHSeekfile or device I/O service
VDHSendVEOIVirtual interrupt service
VDHSetDosDevicemiscellaneous virtual DevHlp service
VDHSetErrormiscellaneous virtual DevHlp service
VDHSetFlagsmiscellaneous virtual DevHlp service
VDHSetIOHookStatehook management service
VDHSetPriorityDOS session control service
VDHSetVIRRVirtual interrupt service
VDHSetVPMExceptDPMI service
VDHSetVPMIntVectorDPMI service
VDHSwitchToVPMDPMI service
VDHSwitchToV86DPMI service
VDHThawVDMDOS session control service
VDHUnlockMemmemory-locking memory management service
VDHUnreservePagespage-granular memory management service
VDHWaitEventSemsemaphore service
VDHWaitVIRRsVirtual interrupt service
VDHWakeIdleidle DOS application management service
VDHWakeVIRRsVirtual interrupt service
VDHWritefile or device I/O service
VDHWriteUBufDPMI service
VDHYieldDOS 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 Assembler Language Syntax.

Defined Constants and Type Definitions

Defined constants, that is, equatestatements in an includefile, 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 Remarkssection 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

VDHAllocDMABufferAllocate DMA buffer
VDHCallOutDMACall virtual DMA device driver
VDHFreeDMABufferFree DMA buffer
VDHRegisterDMAChannelRegister DMA channel



DOS Session Control Services

VDHFreezeVDMFreeze DOS session
VDHHaltSystemCause system halt
VDHIsVDMFrozenDetermine if DOS session is frozen
VDHKillVDMTerminate DOS session
VDHSetPriorityAdjust DOS session scheduler priority
VDHThawVDMAllow frozen DOS session to resume executing
VDHYieldYield the processor



DOS Settings Services

VDHDecodePropertyDecode property string
VDHQueryPropertyQuery virtual device driver property value
VDHRegisterPropertyRegister virtual device driver property



DPMI Services

VDHArmVPMBPHookObtain address of DOS session protect-mode breakpoint
VDHBeginUseVPMStackBegin using DOS session protect-mode stack
VDHChangeVPMIFChange virtual Interrupt Flag (IF)
VDHCheckPagePermCheck Ring 3 page permissions
VDHCheckVPMIntVectorDetermine if DOS session protect-mode handler exists
VDHEndUseVPMStackEnd use of DOS session protect-mode stack
VDHGetSelBaseGet flat base address
VDHGetVPMExceptGet DOS session protect-mode exception vector
VDHGetVPMIntVectorReturn DOS session protect-mode interrupt vector
VDHRaiseExceptionRaise an exception to a DOS session
VDHReadUBufRead from protect-mode address space
VDHSetVPMExceptSet DOS session protect-mode exception vector
VDHSetVPMIntVectorSet DOS session protect-mode interrupt vector
VDHSwitchToVPMSwitch DOS session to protect mode
VDHSwitchToV86Switch DOS session to V86 mode
VDHWriteUBufWrite to protect-mode address space

Note:"VPM", as found in the function names above, stands for Virtual Protect Mode.



File or Device I/O Services

VDHCloseClose a file handle
VDHDevIOCtlIssue device-specific commands
VDHOpenOpen a file or device
VDHPhysicalDiskGet information about partitionable disks
VDHReadRead bytes from file or device
VDHSeekMove read or write file pointer for a handle
VDHWriteWrite bytes to file or device



GDT Selector Services

VDHCreateSelCreate GDT selector to map a linear range
VDHDestroySelDestroy GDT selector
VDHQuerySelGet selector for data or stack address



Hook Management Services

VDHAllocHookAllocate hooks needed for interrupt simulation
VDHArmBPHookObtain address of V86 breakpoint
VDHArmContextHookSet local or global context hook
VDHArmReturnHookSet handler to receive control
VDHArmSTIHookSet handler to receive control
VDHFreeHookDisarm and free hook
VDHInstallIntHookSet handler for V86 interrupt
VDHInstallIOHookInstall I/O port hooks
VDHInstallUserHookInstall handler for DOS session event
VDHQueryHookDataReturns pointer to hook reference data
VDHRemoveIOHookRemove hooks for PIC I/O ports
VDHSetIOHookStateEnable/disable I/O port trapping



Idle DOS Application Management Services

VDHReportPeekReport DOS session polling activity
VDHWakeIdleWake 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

VDHCloseVDDClose virtual device driver
VDHOpenPDDOpen physical device driver
VDHOpenVDDOpen virtual device driver
VDHRegisterVDDRegister virtual device driver entry points
VDHRequestVDDIssue request for virtual device driver operation



Keyboard Services

VDHQueryKeyShiftQuery 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

VDHAllocBlockAllocate block from memory block pool
VDHAllocDOSMemAllocate block of memory from DOS area
VDHAllocMemAllocate small amount of memory
VDHCopyMemCopy from one linear memory address to another
VDHCreateBlockPoolCreate memory block pool
VDHDestroyBlockPoolDestroy memory block pool
VDHExchangeMemExchange contents of two linear memory regions
VDHFreeBlockFree block of memory
VDHFreeMemFree memory



Page-Granular Memory Management Services

VDHAllocPagesAllocate page-aligned memory object
VDHFindFreePagesFind largest available linear memory
VDHFreePagesFree memory object
VDHGetDirtyPageInfoReturn status of dirty bits
VDHInstallFaultHookInstall page fault handler
VDHMapPagesMap specified linear address
VDHQueryFreePagesReturn amount of free virtual memory
VDHReallocPagesReallocate memory object
VDHRemoveFaultHookRemove page fault handler
VDHReservePagesReserve range of linear addresses
VDHUnreservePagesUnreserve range of linear addresses



Memory-Locking Memory Management Services

VDHLockMemVerify access or lock memory
VDHUnlockMemRelease 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
    *Mapping to another linear address
    *Mapping to black holes (don't care) pages
    *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

VDHDevBeepDevice beep virtual DevHlp service
VDHEnumerateVDMsRun worker function for each DOS session
VDHGetCodePageFontReturn information of DOS session code page font
VDHGetErrorGet error code from last virtual DevHlp service
VDHGetFlagsGet DOS Session's EFLAGS Register
VDHHandleFromPIDGet handle for given Process ID
VDHHandleFromSGIDGet DOS session handle from Screen Group ID
VDHPopupDisplay message
VDHPutSysValueSet system value
VDHQueryLinGet linear address for Far16 address
VDHQuerySysValueQuery system value
VDHRegisterAPIRegister API handler
VDHReleaseCodePageFontRelease code page font
VDHSetDosDeviceRegister/install DOS device driver
VDHSetErrorSet error code
VDHSetFlagsSet DOS session flags register



Parallel Port and Printer Services

VDHPrintCloseFlush and close open printers for DOS session



Semaphore Services

VDHCreateSemCreate event or mutex semaphore
VDHDestroySemDestroy semaphore
VDHPostEventSemPost event semaphore
VDHQuerySemQuery semaphore state
VDHReleaseMutexSemRelease mutex semaphore
VDHRequestMutexSemRequest mutex semaphore
VDHResetEventSemReset event semaphore
VDHWaitEventSemWait 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

VDHArmTimerHookSet timer service/handler
VDHDisarmTimerHookCancel timer service



Virtual Interrupt Services

VDHClearVIRRClear virtual IRR
VDHCloseVIRQDeregister IRQ handler
VDHOpenVIRQRegister IRQ handler
VDHQueryVIRQQuery IRQ status on a DOS session
VDHSendVEOISend virtual EOI to VPIC
VDHSetVIRRSet virtual interrupt request register (IRR)
VDHWaitVIRRsWait until interrupt is simulated
VDHWakeVIRRsWake up DOS session



V8086 Stack Manipulation Services

VDHPopIntRemove IRET frame from client DOS session stack
VDHPopRegsPop client DOS session registers from client stack
VDHPopStackPop data off client stack
VDHPushFarCallSimulate Far Call to V86 code
VDHPushIntTransfer control to V86 interrupt handler
VDHPushRegsPush client DOS session registers onto client stack
VDHPushStackPush data onto client stack



VDHAllocBlock

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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 OptionFlagflag when the block is created with VDHCreateBlockPool. 

#include mvdm.h

HBLOCK    SourceBlockPool;  /*  Handle to a memory block pool */
PVOID     rc;

rc = VDHAllocBlock(SourceBlockPool);



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 OptionFlagflag when the block is created with VDHCreateBlockPool. 

#include mvdm.h

HBLOCK    SourceBlockPool;  /*  Handle to a memory block pool */
PVOID     rc;

rc = VDHAllocBlock(SourceBlockPool);



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. VDHGetErrorshould 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. VDHGetErrorshould 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHAllocDMABuffer

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function allocates a DMA buffer. 

#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);



VDHAllocDMABuffer - Format

This function allocates a DMA buffer. 

#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);



VDHAllocDMABuffer Parameter - RequestSize

RequestSize(ULONG) Request Size.

If the Align64kFlag=1, RequestSizeis always less than or equal to 64KB. If the Align64kFlag=0, RequestSizeis 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 VDHAllocDMABufferreturns 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. VDHGetErrorshould be called to determine the nature of the problem.



VDHAllocDMABuffer - Parameters

RequestSize(ULONG) Request Size.

If the Align64kFlag=1, RequestSizeis always less than or equal to 64KB. If the Align64kFlag=0, RequestSizeis 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 VDHAllocDMABufferreturns 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. VDHGetErrorshould 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 VDHFreeDMABufferat 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHAllocDOSMem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function allocates a block of memory from the DOS memory area. Allocations start at 0 bytes and go to 256KB. 

#include mvdm.h

ULONG    BlockSize;  /*  Size of the desired memory block (in bytes) */
PVOID    rc;

rc = VDHAllocDOSMem(BlockSize);



VDHAllocDOSMem - Format

This function allocates a block of memory from the DOS memory area. Allocations start at 0 bytes and go to 256KB. 

#include mvdm.h

ULONG    BlockSize;  /*  Size of the desired memory block (in bytes) */
PVOID    rc;

rc = VDHAllocDOSMem(BlockSize);



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. VDHGetErrorshould be called to determine the nature of the problem. If BlockSize= 0, or if the function is called in an invalid context (see "Context Issues" 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. VDHGetErrorshould be called to determine the nature of the problem. If BlockSize= 0, or if the function is called in an invalid context (see "Context Issues" 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHAllocHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function is used to allocate a hook handle for the arm hook services: Context, STI, Return, Timer, and BP (breakpoint). 

#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);



VDHAllocHook - Format

This function is used to allocate a hook handle for the arm hook services: Context, STI, Return, Timer, and BP (breakpoint). 

#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);



VDHAllocHook Parameter - HookType

HookType(ULONG) Hook type.

Possible values are:

VDH_CONTEXT_HOOK VDHArmContextHook
VDH_STI_HOOK VDHArmSTIHook
VDH_RETURN_HOOK VDHArmReturnHook
VDH_TIMER_HOOK VDHArmTimerHook
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. VDHGetErrorshould be called to determine the nature of the problem. If HookTypeor ArmHookFcnis invalid, a system halt occurs.



VDHAllocHook - Parameters

HookType(ULONG) Hook type.

Possible values are:

VDH_CONTEXT_HOOK VDHArmContextHook
VDH_STI_HOOK VDHArmSTIHook
VDH_RETURN_HOOK VDHArmReturnHook
VDH_TIMER_HOOK VDHArmTimerHook
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. VDHGetErrorshould be called to determine the nature of the problem. If HookTypeor ArmHookFcnis 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 VDHQueryHookDatato get a pointer to any reference data allocated.



VDHAllocHook - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHAllocMem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

ULONG    NumBytes;
ULONG    OptionFlag;  /*  Number of bytes to allocate */
PVOID    rc;

rc = VDHAllocMem(NumBytes, OptionFlag);



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. 

#include mvdm.h

ULONG    NumBytes;
ULONG    OptionFlag;  /*  Number of bytes to allocate */
PVOID    rc;

rc = VDHAllocMem(NumBytes, OptionFlag);



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. VDHGetErrorshould be called to determine the nature of the problem. If either NumBytesor OptionFlagis 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. VDHGetErrorshould be called to determine the nature of the problem. If either NumBytesor OptionFlagis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHAllocPages

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function allocates a page-aligned, page-granular memory object. 

#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);



VDHAllocPages - Format

This function allocates a page-aligned, page-granular memory object. 

#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);



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 VDHAllocPagesattempts 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. VDHGetErrorshould be called to determine the nature of the problem. If the OptionFlagflag 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 VDHAllocPagesattempts 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. VDHGetErrorshould be called to determine the nature of the problem. If the OptionFlagflag 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 VDHAllocPagesis 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 VDHReallocPagesactivity, all pages in the allocation retain the same properties (that is fixed, system, and physical) .



VDHAllocPages - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHArmBPHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function obtains the address of the V86 breakpoint allocated by a previous call to VDHAllocHookwith the VDH_BP_HOOK flag. 

#include mvdm.h

HHOOK     HookHandle;  /*  Hook handle */
VPVOID    rc;

rc = VDHArmBPHook(HookHandle);



VDHArmBPHook - Format

This function obtains the address of the V86 breakpoint allocated by a previous call to VDHAllocHookwith the VDH_BP_HOOK flag. 

#include mvdm.h

HHOOK     HookHandle;  /*  Hook handle */
VPVOID    rc;

rc = VDHArmBPHook(HookHandle);



VDHArmBPHook Parameter - HookHandle

HookHandle(HHOOK) Hook handle allocated with VDHAllocHook.

Hook routine interface: 

 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




VDHArmBPHook Return Value - rc

rc(VPVOID) - returns

Success If the function is successful, it returns a V86 breakpoint address.

Failure If HookHandleis invalid, a system halt occurs.



VDHArmBPHook - Parameters

HookHandle(HHOOK) Hook handle allocated with VDHAllocHook.

Hook routine interface: 

 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


rc(VPVOID) - returns

Success If the function is successful, it returns a V86 breakpoint address.

Failure If HookHandleis 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 pparameter in the hook routine points to the cbRefDatabytes of data allocated by VDHAllocHook.



VDHArmBPHook - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHArmContextHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

HHOOK    HookHandle;  /*  Hook handle allocated with VDHAllocHook */
HVDM     VDMHandle;   /*  DOS session handle */

VDHArmContextHook(HookHandle, VDMHandle);



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. 

#include mvdm.h

HHOOK    HookHandle;  /*  Hook handle allocated with VDHAllocHook */
HVDM     VDMHandle;   /*  DOS session handle */

VDHArmContextHook(HookHandle, VDMHandle);



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: 

 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




VDHArmContextHook - Return Value

Success If the function was successful, it returns nothing.

Failure If HookHandleor VDMHandleis 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: 

 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


Success If the function was successful, it returns nothing.

Failure If HookHandleor VDMHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHArmReturnHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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 VDHPopIntis executed. 

#include mvdm.h

HHOOK    HookHandle;   /*  Hook handle */
ULONG    RetHookType;  /*  Return hook type */
BOOL     rc;

rc = VDHArmReturnHook(HookHandle, RetHookType);



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 VDHPopIntis executed. 

#include mvdm.h

HHOOK    HookHandle;   /*  Hook handle */
ULONG    RetHookType;  /*  Return hook type */
BOOL     rc;

rc = VDHArmReturnHook(HookHandle, RetHookType);



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
VDHARH_NORMAL_RET
VDHARH_RECURSIVE_IRET
VDHARH_RECURSIVE_RET
VDHARH_CSEIP_HOOK
VDHARH_RECURSIVE_CSEIP_HOOK

Hook routine interface: 

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




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 HookHandleis 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
VDHARH_NORMAL_RET
VDHARH_RECURSIVE_IRET
VDHARH_RECURSIVE_RET
VDHARH_CSEIP_HOOK
VDHARH_RECURSIVE_CSEIP_HOOK

Hook routine interface: 

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


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 HookHandleis 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 VDHPushFarCallhas 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
    *After VDHPushInthas 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 VDHPushIntor 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHArmSTIHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

HHOOK    HookHandle;  /*  Hook handle allocated with VDHAllocHook */
HVDM     VDMHandle;   /*  DOS session handle */

VDHArmSTIHook(HookHandle, VDMHandle);



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. 

#include mvdm.h

HHOOK    HookHandle;  /*  Hook handle allocated with VDHAllocHook */
HVDM     VDMHandle;   /*  DOS session handle */

VDHArmSTIHook(HookHandle, VDMHandle);



VDHArmSTIHook Parameter - HookHandle

HookHandle(HHOOK) Hook handle allocated with VDHAllocHook.



VDHArmSTIHook Parameter - VDMHandle

VDMHandle(HVDM) DOS session handle.

Hook routine interface: 

 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




VDHArmSTIHook - Return Value

Success If the function was successful, it returns nothing.

Failure If either HookHandleor VDMHandleis 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: 

 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


Success If the function was successful, it returns nothing.

Failure If either HookHandleor VDMHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHArmTimerHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

HHOOK    HookHandle;  /*  Timer hook handle */
ULONG    Duration;    /*  Duration of the timeout in milliseconds */
HVDM     VDMHandle;   /*  DOS session handle */

VDHArmTimerHook(HookHandle, Duration, VDMHandle);



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. 

#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);



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 HookHandleis called at interrupt time.

Hook routine interface: 

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.




VDHArmTimerHook - Return Value

Success If the function is successful, it returns nothing.

Failure If either Durationor HookHandleis 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 HookHandleis called at interrupt time.

Hook routine interface: 

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.


Success If the function is successful, it returns nothing.

Failure If either Durationor HookHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHArmVPMBPHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function obtains the address of the DOS session's protected-mode breakpoint allocated by a previous call to VDHAllocHookwith the VDH_BP_ HOOK flag. 

#include mvdm.h

HHOOK    HookHandle;  /*  Hook handle allocated with VDHAllocHook */
FPFN     rc;

rc = VDHArmVPMBPHook(HookHandle);



VDHArmVPMBPHook - Format

This function obtains the address of the DOS session's protected-mode breakpoint allocated by a previous call to VDHAllocHookwith the VDH_BP_ HOOK flag. 

#include mvdm.h

HHOOK    HookHandle;  /*  Hook handle allocated with VDHAllocHook */
FPFN     rc;

rc = VDHArmVPMBPHook(HookHandle);



VDHArmVPMBPHook Parameter - HookHandle

HookHandle(HHOOK) Hook handle allocated with VDHAllocHook.

The hook routine interface: 

 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




VDHArmVPMBPHook Return Value - rc

rc(FPFN) - returns

Success If the function is successful, it returns a DOS session protected- mode breakpoint address.

Failure If HookHandleis invalid, a system halt occurs.



VDHArmVPMBPHook - Parameters

HookHandle(HHOOK) Hook handle allocated with VDHAllocHook.

The hook routine interface: 

 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


rc(FPFN) - returns

Success If the function is successful, it returns a DOS session protected- mode breakpoint address.

Failure If HookHandleis 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 pparameter in the hook routine points to the RefDataSizebytes of data allocated by VDHAllocHook.

VDHArmVPMBPHookprovides 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 VDHSetVPMIntVector), but will have to be rehooked each time a DPMI task starts (see VDHInstallUserHook).

There must be a protected-mode DPMI client running in the DOS session before calling this function.



VDHArmVPMBPHook - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHBeginUseVPMStack

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

VOID    ;

VDHBeginUseVPMStack();



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. 

#include mvdm.h

VOID    ;

VDHBeginUseVPMStack();



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHCallOutDMA

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

VOID    ;

VDHCallOutDMA();



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. 

#include mvdm.h

VOID    ;

VDHCallOutDMA();



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHChangeVPMIF

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function changes the virtual Interrupt Flag (IF) that enables or disables protected-mode interrupts. This change is reflected in a bit in the flVDMStatuskernel variable (see "Notes" under Purpose). If the STI hooks are waiting and interrupts are enabled, the hooks are called. 

#include mvdm.h

BOOL    SetIFFlag;  /*  Indicates whether to turn the IF flag on or off */
BOOL    rc;

rc = VDHChangeVPMIF(SetIFFlag);



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 flVDMStatuskernel variable (see "Notes" under Purpose). If the STI hooks are waiting and interrupts are enabled, the hooks are called. 

#include mvdm.h

BOOL    SetIFFlag;  /*  Indicates whether to turn the IF flag on or off */
BOOL    rc;

rc = VDHChangeVPMIF(SetIFFlag);



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 flVDMStatuskernel variable is exported from the kernel. Any virtual device driver can refer to it directly. flVDMStatusis a DD-sized variable that contains various DOS session status flags relating to protected mode and the DOS Protected Mode Interface (DPMI).

The flVDMStatusflags indicate:

  • DPMI was initialized (protected mode was enabled)
    *16-bit or 32-bit
    *The current execution mode (V86 or protected)

These flags and their values are: 

   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? */



VDHChangeVPMIF - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHCheckPagePerm

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.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);



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. 

#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);



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?
VPMPG_W Are the pages writable?
VPMPG_R Are the pages readable (valid)?
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?
VPMPG_W Are the pages writable?
VPMPG_R Are the pages readable (valid)?
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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHCheckVPMIntVector

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function returns a nonzero value if the application protected-mode interrupt vector is set. 

#include mvdm.h

ULONG    Vector;  /*  Interrupt vector number */
BOOL     rc;

rc = VDHCheckVPMIntVector(Vector);



VDHCheckVPMIntVector - Format

This function returns a nonzero value if the application protected-mode interrupt vector is set. 

#include mvdm.h

ULONG    Vector;  /*  Interrupt vector number */
BOOL     rc;

rc = VDHCheckVPMIntVector(Vector);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHClearVIRR

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

HVDM    VDMHandle;  /*  DOS session handle */
HIRQ    IRQHandle;  /*  IRQ handle from VDHOpenVIRQ */

VDHClearVIRR(VDMHandle, IRQHandle);



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. 

#include mvdm.h

HVDM    VDMHandle;  /*  DOS session handle */
HIRQ    IRQHandle;  /*  IRQ handle from VDHOpenVIRQ */

VDHClearVIRR(VDMHandle, IRQHandle);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHClose

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function closes a file or device that was opened with VDHOpen. 

#include mvdm.h

HFILE    FileHandle;  /*  Handle to the file or device to close */

VDHClose(FileHandle);



VDHClose - Format

This function closes a file or device that was opened with VDHOpen. 

#include mvdm.h

HFILE    FileHandle;  /*  Handle to the file or device to close */

VDHClose(FileHandle);



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 FileHandleis 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 FileHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHCloseVDD

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

HVDD    VDDHandle;  /*  Handle to the file or device to close */

VDHCloseVDD(VDDHandle);



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. 

#include mvdm.h

HVDD    VDDHandle;  /*  Handle to the file or device to close */

VDHCloseVDD(VDDHandle);



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 VDMHandleis 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 VDMHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHCloseVIRQ

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function closes the virtual IRQ handle passed to it. 

#include mvdm.h

HIRQ    IRQHandl;  /*  Handle of the virtual device driver to close */

VDHCloseVIRQ(IRQHandl);



VDHCloseVIRQ - Format

This function closes the virtual IRQ handle passed to it. 

#include mvdm.h

HIRQ    IRQHandl;  /*  Handle of the virtual device driver to close */

VDHCloseVIRQ(IRQHandl);



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 IRQHandleis 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 IRQHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHCopyMem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function copies memory from one user linear address to another. 

#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);



VDHCopyMem - Format

This function copies memory from one user linear address to another. 

#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);



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 NumBytesis 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 NumBytesis 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 "don't care" 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, VDHLockMemis 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 VDHCopyMemis made in the context of some other process.



VDHCopyMem - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHCreateBlockPool

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

ULONG     BlockSize;   /*  Size of block to initialize (in bytes) */
ULONG     OptionFlag;  /*  Allocation options bit flag */
HBLOCK    rc;

rc = VDHCreateBlockPool(BlockSize, OptionFlag);



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. 

#include mvdm.h

ULONG     BlockSize;   /*  Size of block to initialize (in bytes) */
ULONG     OptionFlag;  /*  Allocation options bit flag */
HBLOCK    rc;

rc = VDHCreateBlockPool(BlockSize, OptionFlag);



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). VDHGetErrorshould be called to determine the nature of the problem. If OptionFlagis invalid, or if BlockSizeis 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). VDHGetErrorshould be called to determine the nature of the problem. If OptionFlagis invalid, or if BlockSizeis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHCreateSel

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.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);



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. 

#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);



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 BufferSizeis 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 BufferSizeis 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. VDHDestroySelmust be called when finished with this pointer.



VDHCreateSel - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHCreateSem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function is used to create an event or mutex semaphore. 

#include mvdm.h

PHVDHSEM    SemHandlePointer;  /*  Semaphore handle address */
ULONG       SemType;           /*  Type of semaphore of create */
BOOL        rc;

rc = VDHCreateSem(SemHandlePointer, SemType);



VDHCreateSem - Format

This function is used to create an event or mutex semaphore. 

#include mvdm.h

PHVDHSEM    SemHandlePointer;  /*  Semaphore handle address */
ULONG       SemType;           /*  Type of semaphore of create */
BOOL        rc;

rc = VDHCreateSem(SemHandlePointer, SemType);



VDHCreateSem Parameter - SemHandlePointer

SemHandlePointer(PHVDHSEM) Semaphore handle address.



VDHCreateSem Parameter - SemType

SemType(ULONG) Type of semaphore to create.

Values are:

VDH_EVENTSEM Event semaphore
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. VDHGetErrorshould 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
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. VDHGetErrorshould 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 VDHDestroySemwhen the DOS session they are associated with is terminated.



VDHCreateSem - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHDecodeProperty

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function decodes the specified format of a property string. (See Notes ) 

#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);



VDHDecodeProperty - Format

This function decodes the specified format of a property string. (See Notes ) 

#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);



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
VDH_DP_HEX Hex



VDHDecodeProperty Return Value - rc

rc(BOOL) - returns

Success If the function is successful, it returns a nonzero value and the ppPropertypointer is modified to point to the next range in the property string. StartNumberPtrand EndNumberPtrwill have the range values. ppPropertyis returned NULL after processing the last range.

Failure If the function fails, it returns 0, indicating an invalid parameter. If BaseFlagcontains an invalid value or if ppPropertyis 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
VDH_DP_HEX Hex

rc(BOOL) - returns

Success If the function is successful, it returns a nonzero value and the ppPropertypointer is modified to point to the next range in the property string. StartNumberPtrand EndNumberPtrwill have the range values. ppPropertyis returned NULL after processing the last range.

Failure If the function fails, it returns 0, indicating an invalid parameter. If BaseFlagcontains an invalid value or if ppPropertyis 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, EndNumberPtris 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 StartNumberPtror EndNumberPtrmight 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: 

String Syntax = "N1-N2,N3-N4,N5,N6-N7,..."

Notice that Nxare valid numbers in a specified base.



VDHDecodeProperty - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHDestroyBlockPool

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function releases a memory block pool. 

#include mvdm.h

HBLOCK    PoolHandle;  /*  Handle to the memory block pool to release */
HBLOCK    rc;

rc = VDHDestroyBlockPool(PoolHandle);



VDHDestroyBlockPool - Format

This function releases a memory block pool. 

#include mvdm.h

HBLOCK    PoolHandle;  /*  Handle to the memory block pool to release */
HBLOCK    rc;

rc = VDHDestroyBlockPool(PoolHandle);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHDestroySel

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function destroys a GDT selector created by VDHCreateSel. 

#include mvdm.h

SEL     GDTSelector;  /*  GDT selector to destroy */

VDHDestroySel(GDTSelector);



VDHDestroySel - Format

This function destroys a GDT selector created by VDHCreateSel. 

#include mvdm.h

SEL     GDTSelector;  /*  GDT selector to destroy */

VDHDestroySel(GDTSelector);



VDHDestroySel Parameter - GDTSelector

GDTSelector(SEL) GDT selector to be destroyed.



VDHDestroySel - Return Value

Success If the function is successful, it returns nothing.

Failure If GDTSelectorwas 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 GDTSelectorwas 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 VDHCreateSelthat map the terminating DOS session must be destroyed.



VDHDestroySel - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHDestroySem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function destroys a semaphore previously created with VDHCreateSem. The semaphore must be posted or unowned before calling this service. 

#include mvdm.h

HVDHSEM    SemHandle;  /*  Semaphore handle to destroy */

VDHDestroySem(SemHandle);



VDHDestroySem - Format

This function destroys a semaphore previously created with VDHCreateSem. The semaphore must be posted or unowned before calling this service. 

#include mvdm.h

HVDHSEM    SemHandle;  /*  Semaphore handle to destroy */

VDHDestroySem(SemHandle);



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 SemHandleis 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 SemHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHDevBeep

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function performs the preempt beep request on behalf of the requesting virtual device driver. 

#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);



VDHDevBeep - Format

This function performs the preempt beep request on behalf of the requesting virtual device driver. 

#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);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHDevIOCtl

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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 DosDevIOCtlAPI. Refer to the OS/2 Control Program Programming Referencefor a complete description of each DosDevIOCtlAPI parameter. 

#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);



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 DosDevIOCtlAPI. Refer to the OS/2 Control Program Programming Referencefor a complete description of each DosDevIOCtlAPI parameter. 

#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);



VDHDevIOCtl Parameter - DevHandle

DevHandle(HFILE) Device handle returned by VDHOpenor 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. ParmLengthInOutcan 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. ParmLengthInOutcan 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. VDHGetErrorshould be called to determine the nature of the problem. VDHGetErrorcan return the following errors:

ERROR_INVALID_HANDLE
ERROR_INVALID_FUNCTION
ERROR_INVALID_CATEGORY
ERROR_INVALID_DRIVE
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 VDHOpenor 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. ParmLengthInOutcan 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. ParmLengthInOutcan 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. VDHGetErrorshould be called to determine the nature of the problem. VDHGetErrorcan return the following errors:

ERROR_INVALID_HANDLE
ERROR_INVALID_FUNCTION
ERROR_INVALID_CATEGORY
ERROR_INVALID_DRIVE
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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHDisarmTimerHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function cancels a timer that was installed by VDHArmTimerHookbefore the handler was called. 

#include mvdm.h

HHOOK    TimerHook;  /*  Handle to the timer hook to disarm */
BOOL     rc;

rc = VDHDisarmTimerHook(TimerHook);



VDHDisarmTimerHook - Format

This function cancels a timer that was installed by VDHArmTimerHookbefore the handler was called. 

#include mvdm.h

HHOOK    TimerHook;  /*  Handle to the timer hook to disarm */
BOOL     rc;

rc = VDHDisarmTimerHook(TimerHook);



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). VDHGetErrorshould be called to determine the nature of the problem. If TimerHookis 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). VDHGetErrorshould be called to determine the nature of the problem. If TimerHookis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHEndUseVPMStack

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

VOID    ;

VDHEndUseVPMStack();



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. 

#include mvdm.h

VOID    ;

VDHEndUseVPMStack();



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHEnumerateVDMs

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

PENUMHOOK    WorkerFcn;  /*  Worker function */
ULONG        FcnData;    /*  Function-specific data to be passed each call */
BOOL         rc;

rc = VDHEnumerateVDMs(WorkerFcn, FcnData);



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. 

#include mvdm.h

PENUMHOOK    WorkerFcn;  /*  Worker function */
ULONG        FcnData;    /*  Function-specific data to be passed each call */
BOOL         rc;

rc = VDHEnumerateVDMs(WorkerFcn, FcnData);



VDHEnumerateVDMs Parameter - WorkerFcn

WorkerFcn(PENUMHOOK) Worker function, the routine that does the work.

The worker function uses the following interface: 

 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




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: 

 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


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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHExchangeMem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function exchanges the contents of two regions of linear address space . Overlapping regions are not supported. 

#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);



VDHExchangeMem - Format

This function exchanges the contents of two regions of linear address space . Overlapping regions are not supported. 

#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);



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). VDHGetErrorshould 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). VDHGetErrorshould 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHFindFreePages

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

PVOID     StartAddress;  /*  Starting address */
PULONG    Pages;         /*  Size of the range (in pages) */
PVOID     rc;

rc = VDHFindFreePages(StartAddress, Pages);



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. 

#include mvdm.h

PVOID     StartAddress;  /*  Starting address */
PULONG    Pages;         /*  Size of the range (in pages) */
PVOID     rc;

rc = VDHFindFreePages(StartAddress, Pages);



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 Pagesto the size of the region found (in pages).

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould 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 Pagesto the size of the region found (in pages).

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHFreeBlock

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

HBLOCK    PoolHandle;   /*  Handle to a memory block pool */
PVOID     BlockToFree;  /*  Address of the memory block to free */

VDHFreeBlock(PoolHandle, BlockToFree);



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. 

#include mvdm.h

HBLOCK    PoolHandle;   /*  Handle to a memory block pool */
PVOID     BlockToFree;  /*  Address of the memory block to free */

VDHFreeBlock(PoolHandle, BlockToFree);



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 BlockPoolis not a valid handle to a memory block pool, or if BlockToFreeis not a block allocated from the BlockPoolmemory 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 BlockPoolis not a valid handle to a memory block pool, or if BlockToFreeis not a block allocated from the BlockPoolmemory 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHFreeDMABuffer

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function frees a DMA buffer previously allocated by VDHAllocDMABuffer. 

#include mvdm.h

PVOID    LinearAddress;  /*  Starting linear address of the DMA buffer */

VDHFreeDMABuffer(LinearAddress);



VDHFreeDMABuffer - Format

This function frees a DMA buffer previously allocated by VDHAllocDMABuffer. 

#include mvdm.h

PVOID    LinearAddress;  /*  Starting linear address of the DMA buffer */

VDHFreeDMABuffer(LinearAddress);



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 LinearAddressis 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 LinearAddressis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHFreeHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function disarms and frees a hook. 

#include mvdm.h

HHOOK    HookHandle;  /*  Hook handle from VDHAllocHook */

VDHFreeHook(HookHandle);



VDHFreeHook - Format

This function disarms and frees a hook. 

#include mvdm.h

HHOOK    HookHandle;  /*  Hook handle from VDHAllocHook */

VDHFreeHook(HookHandle);



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 HookHandleis 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 HookHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHFreeMem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function frees memory that was previously allocated by VDHAllocMem. 

#include mvdm.h

PVOID    MemAddress;  /*  Address of the memory block to free */

VDHFreeMem(MemAddress);



VDHFreeMem - Format

This function frees memory that was previously allocated by VDHAllocMem. 

#include mvdm.h

PVOID    MemAddress;  /*  Address of the memory block to free */

VDHFreeMem(MemAddress);



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 MemAddressis 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 MemAddressis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHFreePages

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function frees a memory object. All the memory associated with the memory object is released. 

#include mvdm.h

PVOID    ObjectAddress;  /*  Address of the memory object to free */

VDHFreePages(ObjectAddress);



VDHFreePages - Format

This function frees a memory object. All the memory associated with the memory object is released. 

#include mvdm.h

PVOID    ObjectAddress;  /*  Address of the memory object to free */

VDHFreePages(ObjectAddress);



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 ObjectAddresswas not allocated by VDHAllocPagesor 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 ObjectAddresswas not allocated by VDHAllocPagesor 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 VDHAllocPagesor 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 VDHFreePagesis not used.



VDHFreePages - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHFreezeVDM

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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 VDHThawVDMis 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 VDHFreezeVDMis called until the matching VDHThawVDMis called. 

#include mvdm.h

HVDM    VDMHandle;  /*  Handle to the DOS session to freeze */
BOOL    rc;

rc = VDHFreezeVDM(VDMHandle);



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 VDHThawVDMis 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 VDHFreezeVDMis called until the matching VDHThawVDMis called. 

#include mvdm.h

HVDM    VDMHandle;  /*  Handle to the DOS session to freeze */
BOOL    rc;

rc = VDHFreezeVDM(VDMHandle);



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). VDHGetErrorshould be called to determine the nature of the problem. If VDMHandleis 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). VDHGetErrorshould be called to determine the nature of the problem. If VDMHandleis 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 VDHFreezeVDMcall adds one to this count. Each VDHThawVDMcall 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, VDHFreezeVDMreturns VDHERR_FROZEN_LIMIT.



VDHFreezeVDM - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHGetCodePageFont

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.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);



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. 

#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);



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). VDHGetErrorshould 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). VDHGetErrorshould 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, VDHReleaseCodePageFontmust 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHGetDirtyPageInfo

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.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);



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. 

#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);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHGetError

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function returns the error code from the last virtual DevHlp service called. 

#include mvdm.h

VOID     ;
ULONG    rc;

rc = VDHGetError();



VDHGetError - Format

This function returns the error code from the last virtual DevHlp service called. 

#include mvdm.h

VOID     ;
ULONG    rc;

rc = VDHGetError();



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. VDHGetErrorand VDHSetErrorwork 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHGetFlags

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function gets the DOS session's EFlags Register. 

#include mvdm.h

ULONG    ulFlagsAddr;  /*  DOS session flag address. */

VDHGetFlags(ulFlagsAddr);



VDHGetFlags - Format

This function gets the DOS session's EFlags Register. 

#include mvdm.h

ULONG    ulFlagsAddr;  /*  DOS session flag address. */

VDHGetFlags(ulFlagsAddr);



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 VDHArmSTIHookworks correctly.

Getting the Interrupt Flag (IF) must be under 8086 emulation control due to virtual mode extensions and DPMI.



VDHGetFlags - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHGetSelBase

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function returns the base address for a Local Descriptor Table (LDT) selector. 

#include mvdm.h

SEL       Selector;      /*  LDT selector */
PULONG    pBasePointer;  /*  Pointer for returned address */
BOOL      rc;

rc = VDHGetSelBase(Selector, pBasePointer);



VDHGetSelBase - Format

This function returns the base address for a Local Descriptor Table (LDT) selector. 

#include mvdm.h

SEL       Selector;      /*  LDT selector */
PULONG    pBasePointer;  /*  Pointer for returned address */
BOOL      rc;

rc = VDHGetSelBase(Selector, pBasePointer);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHGetVPMExcept

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function gets the current value from the protected-mode exception table. 

#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);



VDHGetVPMExcept - Format

This function gets the current value from the protected-mode exception table. 

#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);



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.
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.
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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHGetVPMIntVector

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

ULONG    Vector;                 /*  Interrupt vector number */
PFPFN    HandlerAddressPointer;  /*  Pointer for return of handler address */
BOOL     rc;

rc = VDHGetVPMIntVector(Vector, HandlerAddressPointer);



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. 

#include mvdm.h

ULONG    Vector;                 /*  Interrupt vector number */
PFPFN    HandlerAddressPointer;  /*  Pointer for return of handler address */
BOOL     rc;

rc = VDHGetVPMIntVector(Vector, HandlerAddressPointer);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHHaltSystem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function causes a system halt. 

#include mvdm.h

VOID    ;

VDHHaltSystem();



VDHHaltSystem - Format

This function causes a system halt. 

#include mvdm.h

VOID    ;

VDHHaltSystem();



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 VDHHaltSystemis an extremely drastic action. Calling VDHPopupand VDHKillVDMis the preferred method for handling a problem. VDHHaltSystemis 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. VDHPopupis called prior to VDHHaltSystemto tell the user what has happened.



VDHHaltSystem - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHHandleFromPID

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function returns the DOS session handle for a given Process ID. 

#include mvdm.h

PID     ProcessID;  /*  A DOS session process ID */
HVDM    rc;

rc = VDHHandleFromPID(ProcessID);



VDHHandleFromPID - Format

This function returns the DOS session handle for a given Process ID. 

#include mvdm.h

PID     ProcessID;  /*  A DOS session process ID */
HVDM    rc;

rc = VDHHandleFromPID(ProcessID);



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). VDHGetErrorshould 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). VDHGetErrorshould 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHHandleFromSGID

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function determines the DOS session handle given the Screen Group ID. 

#include mvdm.h

SGID    ScreenGroupID;  /*  Screen Group ID */
HVDM    rc;

rc = VDHHandleFromSGID(ScreenGroupID);



VDHHandleFromSGID - Format

This function determines the DOS session handle given the Screen Group ID. 

#include mvdm.h

SGID    ScreenGroupID;  /*  Screen Group ID */
HVDM    rc;

rc = VDHHandleFromSGID(ScreenGroupID);



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). VDHGetErrorshould 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). VDHGetErrorshould 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHInstallFaultHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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 "not present" by the Page Manager. 

#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);



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 "not present" by the Page Manager. 

#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);



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: 

 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




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: 

 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


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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHInstallIntHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.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);



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. 

#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);



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 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: 

 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




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). VDHGetErrorshould be called to determine the nature of the problem. If HookFcnis invalid or if Vectoris 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 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: 

 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


rc(BOOL) - returns

Success If the function was successful, it returns a nonzero value.

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould be called to determine the nature of the problem. If HookFcnis invalid or if Vectoris 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 VDHPopIntis needed to remove the software interrupt (so that the ROM code is not executed).



VDHInstallIntHook - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHInstallIOHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function is used to install I/O port hooks. 

#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);



VDHInstallIOHook - Format

This function is used to install I/O port hooks. 

#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);



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.
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). VDHGetErrorshould be called to determine the nature of the problem. If IOPortHookEntryis invalid, or if StartingPortor NumPortsare 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.
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). VDHGetErrorshould be called to determine the nature of the problem. If IOPortHookEntryis invalid, or if StartingPortor NumPortsare 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: 

    VDHInstallIOHook (reserved,0x100,4,&iohA,NULL);

The I/O instructions to each address with the length indicated cause the following hooks to be called: 

/--------------------------------------------------------------\
|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)                |
\--------------------------------------------------------------/

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: 

typedef struct ioh {
    PBIH ioh_pbihByteInput;
    PBOH ioh_pbohByteOutput;
    PWIH ioh_pwihWordInput;
    PWOH ioh_pwohWordOutput;
    POTH ioh_pothOther;
} IOH;


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


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


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


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


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
                 "VDHInstallIOHook" in Assembler Language Syntax.

                 The C hook has to use EAX to return status, and so needs
                 the additional parameter.



VDHInstallIOHook - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHInstallUserHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function is used to set a handler for a specific DOS session event. 

#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);



VDHInstallUserHook - Format

This function is used to set a handler for a specific DOS session event. 

#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);



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
VDM_CREATE DOS session creation
VDM_TERMINATE DOS session termination
VDM_FOREGROUND DOS session to the foreground
VDM_BACKGROUND DOS session to the background
VDM_CREATE_DONE DOS session creation completed successfully
VDM_VDD_CREATE_DONE DOS session virtual device driver creation completed
VDM_PDB_DESTROY DOS Program Data Block (PDB) destroyed in DOS session
VDM_PDB_CHANGE PDB changed in DOS session
VDM_CODEPAGE_CHANGE Code page change event
VDM_TITLE_CHANGE DOS session title change event
VDM_MEMORY_MAPPED_IN Pages mapped into a DOS session (0 to 1MB+64KB)
VDM_MEMORY_UN_MAPPED Pages unmapped from a DOS session (0 to 1MB+64KB).
VDM_BEGIN_VPM_TASK Protected-mode task has started
VDM_END_VPM_TASK Protected-mode task has ended

The interfaces for the UserHookhandlers (depending on the event that is handled) are: 

 RETCODE HOOKENTRY pfnExit()
         ENTRY     None
         EXIT      None
         CONTEXT   INIT
                   Task


 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


 RETCODE HOOKENTRY pfnTerminate(hvdm)
         ENTRY         hvdm - DOS session being terminated
         EXIT-SUCCESS  Return a nonzero value
         EXIT-FAILURE  Return 0
         CONTEXT       DOS session-task


 RETCODE HOOKENTRY pfnForeground(hvdm)
         ENTRY     hvdm - DOS session coming foreground
         EXIT      None
         CONTEXT   Task


 RETCODE HOOKENTRY pfnBackground(hvdm)
         ENTRY     hvdm - DOS session going background
         EXIT      None
         CONTEXT   Task


 RETCODE HOOKENTRY pfnCreateDone(hvdm)
         ENTRY     hvdm
         EXIT      None
         CONTEXT   DOS session creation


 RETCODE HOOKENTRY pfnVDDCreateDone(hvdm)
         ENTRY     hvdm
         EXIT      None
         CONTEXT   DOS session Creation


 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


 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


 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


 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.


 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


 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


 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


 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


 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


 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




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
VDM_CREATE DOS session creation
VDM_TERMINATE DOS session termination
VDM_FOREGROUND DOS session to the foreground
VDM_BACKGROUND DOS session to the background
VDM_CREATE_DONE DOS session creation completed successfully
VDM_VDD_CREATE_DONE DOS session virtual device driver creation completed
VDM_PDB_DESTROY DOS Program Data Block (PDB) destroyed in DOS session
VDM_PDB_CHANGE PDB changed in DOS session
VDM_CODEPAGE_CHANGE Code page change event
VDM_TITLE_CHANGE DOS session title change event
VDM_MEMORY_MAPPED_IN Pages mapped into a DOS session (0 to 1MB+64KB)
VDM_MEMORY_UN_MAPPED Pages unmapped from a DOS session (0 to 1MB+64KB).
VDM_BEGIN_VPM_TASK Protected-mode task has started
VDM_END_VPM_TASK Protected-mode task has ended

The interfaces for the UserHookhandlers (depending on the event that is handled) are: 

 RETCODE HOOKENTRY pfnExit()
         ENTRY     None
         EXIT      None
         CONTEXT   INIT
                   Task


 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


 RETCODE HOOKENTRY pfnTerminate(hvdm)
         ENTRY         hvdm - DOS session being terminated
         EXIT-SUCCESS  Return a nonzero value
         EXIT-FAILURE  Return 0
         CONTEXT       DOS session-task


 RETCODE HOOKENTRY pfnForeground(hvdm)
         ENTRY     hvdm - DOS session coming foreground
         EXIT      None
         CONTEXT   Task


 RETCODE HOOKENTRY pfnBackground(hvdm)
         ENTRY     hvdm - DOS session going background
         EXIT      None
         CONTEXT   Task


 RETCODE HOOKENTRY pfnCreateDone(hvdm)
         ENTRY     hvdm
         EXIT      None
         CONTEXT   DOS session creation


 RETCODE HOOKENTRY pfnVDDCreateDone(hvdm)
         ENTRY     hvdm
         EXIT      None
         CONTEXT   DOS session Creation


 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


 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


 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


 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.


 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


 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


 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


 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


 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


 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


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_Handlerfor Virtual Device Driver A returned successfully, but the Create_Handlerfor Virtual Device Driver B failed. In this case, the Terminate_Handlerfor Virtual Device Driver A will not be called. This should be taken into consideration when deciding what to do in a Create_Handlerand a Create_Done_Handler.



VDHInstallUserHook - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHIsVDMFrozen

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function returns the freeze state of a DOS session. 

#include mvdm.h

HVDM    VDMHandle;  /*  Handle to the DOS session */
BOOL    rc;

rc = VDHIsVDMFrozen(VDMHandle);



VDHIsVDMFrozen - Format

This function returns the freeze state of a DOS session. 

#include mvdm.h

HVDM    VDMHandle;  /*  Handle to the DOS session */
BOOL    rc;

rc = VDHIsVDMFrozen(VDMHandle);



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 VDMHandleis 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 VDMHandleis 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 VDHFreezeVDMfor a full discussion of freeze counting.



VDHIsVDMFrozen - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHKillVDM

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

HVDM    VDMHandle;  /*  Handle to the DOS session to terminate */

VDHKillVDM(VDMHandle);



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. 

#include mvdm.h

HVDM    VDMHandle;  /*  Handle to the DOS session to terminate */

VDHKillVDM(VDMHandle);



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 VDMHandleis 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 VDMHandleis 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 VDHInstallUserHookare 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHLockMem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function verifies that a specified region is accessible in the requested manner, and locks the memory in the requested manner. 

#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);



VDHLockMem - Format

This function verifies that a specified region is accessible in the requested manner, and locks the memory in the requested manner. 

#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);



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.

VDHLockMemfills this array. Each VDHPageList_sstructure describes a single physically contiguous sub-area of the physical memory that was locked. If PagelistArrayPtris set to VDHLM_NO_ADDR, no array is returned. The area that PagelistArrayPtrpoints to must contain enough VDHPageList_sstructures 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 PagelistArrayPtrarray is placed by VDHLockMem. If PagelistArrayPtris set to VDHLM_NO_ADDR, ArrayCountPtris 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 VDHGetErrorto determine the nature of the problem. If NumBytesequals 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.

VDHLockMemfills this array. Each VDHPageList_sstructure describes a single physically contiguous sub-area of the physical memory that was locked. If PagelistArrayPtris set to VDHLM_NO_ADDR, no array is returned. The area that PagelistArrayPtrpoints to must contain enough VDHPageList_sstructures 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 PagelistArrayPtrarray is placed by VDHLockMem. If PagelistArrayPtris set to VDHLM_NO_ADDR, ArrayCountPtris 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 VDHGetErrorto determine the nature of the problem. If NumBytesequals 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 VDHUnlockMemto 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 VDHCopyMemand VDHExchangeMem.

VDHMapPages, VDHReallocPages, and VDHFreePageswill block if applied to pages that are locked. They unblock when the lock is released.



VDHLockMem - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHMapPages

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function maps a linear address region in the V86 address space. 

#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);



VDHMapPages - Format

This function maps a linear address region in the V86 address space. 

#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);



VDHMapPages Parameter - pvdhmsSourceRegion

pvdhmsSourceRegion(PVDHMAPSOURCE) Pointer to VDHMAPSOURCE structure.

VDHMAPSOURCE is the source region definition for VDHMapPageswith a data structure as follows: 

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;




VDHMapPages Parameter - pvdhmtTargetRegion

pvdhmtTargetRegion(PVDHMAPTARGET) Target region definition. Pointer to VDHMAPTARGET structure.

VDHMAPTARGET is the target region definition for VDHMapPageswith a data structure as follows: 

typedef struct VDHMapTarget_s {
    ULONG   vdhmt_laddr;     /* Address in V86-space to be      */
                             /* mapped.                         */
                             /* (0 <= vdhmt_laddr < 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;




VDHMapPages Parameter - flMappingFlag

flMappingFlag(ULONG) Mapping options flag.

Possible values are:

VDHMT_INVALID Make target region pages invalid. vdhmt_hmapcan 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 pvdhmsSourceRegionis ignored.

VDHMT_LINEAR Map linear source region into target region. vdhms_laddrcontains 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 VDHAllocPagesor VDHReallocPages. After a successful mapping, the target region aliases the corresponding region of the source.

vdhms_hobjmust be 0 (zero) the first time a newly allocated or reallocated source object is mapped. On a successful mapping, vdhms_hobjis 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_laddrcontains the physical address to map at the start of the target region. vdhms_hobjis ignored.

VDHMT_BLACK_HOLE Map target region to black hole pages. pvdhmsSourceRegionis 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). VDHGetErrorshould be called to determine the nature of the problem.



VDHMapPages - Parameters

pvdhmsSourceRegion(PVDHMAPSOURCE) Pointer to VDHMAPSOURCE structure.

VDHMAPSOURCE is the source region definition for VDHMapPageswith a data structure as follows: 

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;


pvdhmtTargetRegion(PVDHMAPTARGET) Target region definition. Pointer to VDHMAPTARGET structure.

VDHMAPTARGET is the target region definition for VDHMapPageswith a data structure as follows: 

typedef struct VDHMapTarget_s {
    ULONG   vdhmt_laddr;     /* Address in V86-space to be      */
                             /* mapped.                         */
                             /* (0 <= vdhmt_laddr < 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;


flMappingFlag(ULONG) Mapping options flag.

Possible values are:

VDHMT_INVALID Make target region pages invalid. vdhmt_hmapcan 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 pvdhmsSourceRegionis ignored.

VDHMT_LINEAR Map linear source region into target region. vdhms_laddrcontains 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 VDHAllocPagesor VDHReallocPages. After a successful mapping, the target region aliases the corresponding region of the source.

vdhms_hobjmust be 0 (zero) the first time a newly allocated or reallocated source object is mapped. On a successful mapping, vdhms_hobjis 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_laddrcontains the physical address to map at the start of the target region. vdhms_hobjis ignored.

VDHMT_BLACK_HOLE Map target region to black hole pages. pvdhmsSourceRegionis ignored.

rc(BOOL) - returns

Success If the function is successful, it returns a nonzero value.

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould 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
    *Specific physical addresses (for physical devices)
    *Undefined memory (black holes)
    *Invalid pages (the unmapped state, which is the default state for reserved pages)

VDHMapPagesalso 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 VDHAllocPagesor VDHReallocPages
    *Physical addresses for a device
    *Black hole (undefined memory) addresses that are read or written but do not retain their values
    *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. VDHMapPagesand VDHAllocPagescan 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHOpen

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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 DosOpenAPI. Refer to the OS/2 Control Program Programming Referencefor a complete descriptions of each DosOpenAPI parameter. 

#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);



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 DosOpenAPI. Refer to the OS/2 Control Program Programming Referencefor a complete descriptions of each DosOpenAPI parameter. 

#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);



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
VDHOPEN_FILE_CREATED File created
VDHOPEN_FILE_TRUNCATED File replaced



VDHOpen Parameter - OpenMode

OpenMode(ULONG) Describes the mode of the Openfunction.



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, VDHGetErrorshould be called to determine the nature of the problem. VDHGetErrorcan return the following errors:

ERROR_DISK_FULL
ERROR_OPEN_FAILED
ERROR_FILE_NOT_FOUND
ERROR_INVALID_PARAMETER
ERROR_PATH_NOT_FOUND
ERROR_ACCESS_DENIED
ERROR_DRIVE_LOCKED
ERROR_NOT_DOS_DISK
ERROR_SHARING_BUFFER_EXCEEDED
ERROR_SHARING_VIOLATION
ERROR_INVALID_ACCESS
ERROR_CANNOT_MAKE
ERROR_TOO_MANY_OPEN_FILES
ERROR_NOT_ENOUGH_MEMORY

If the function is called at other than DOS session-task time, or if the pszFileNamepointer 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
VDHOPEN_FILE_CREATED File created
VDHOPEN_FILE_TRUNCATED File replaced

OpenMode(ULONG) Describes the mode of the Openfunction.

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, VDHGetErrorshould be called to determine the nature of the problem. VDHGetErrorcan return the following errors:

ERROR_DISK_FULL
ERROR_OPEN_FAILED
ERROR_FILE_NOT_FOUND
ERROR_INVALID_PARAMETER
ERROR_PATH_NOT_FOUND
ERROR_ACCESS_DENIED
ERROR_DRIVE_LOCKED
ERROR_NOT_DOS_DISK
ERROR_SHARING_BUFFER_EXCEEDED
ERROR_SHARING_VIOLATION
ERROR_INVALID_ACCESS
ERROR_CANNOT_MAKE
ERROR_TOO_MANY_OPEN_FILES
ERROR_NOT_ENOUGH_MEMORY

If the function is called at other than DOS session-task time, or if the pszFileNamepointer 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 VDHOpendoes 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 VDHOpenhandles and the handles returned from INT 21H $Open cannot be used interchangeably.



VDHOpen - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHOpenPDD

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.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);



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. 

#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);



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: 

 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




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 " RegisterPDD" in the OS/2 Physical Device Driver Referencefor a description of the physical device driver's IDC function.

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould 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: 

 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


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 " RegisterPDD" in the OS/2 Physical Device Driver Referencefor a description of the physical device driver's IDC function.

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHOpenVDD

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function returns a handle to a virtual device driver that can be used with VDHRequestVDDto 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.h

PSZ     VDDName;  /*  Pointer to the name of the virtual device driver to open */
HVDD    rc;

rc = VDHOpenVDD(VDDName);



VDHOpenVDD - Format

This function returns a handle to a virtual device driver that can be used with VDHRequestVDDto 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.h

PSZ     VDDName;  /*  Pointer to the name of the virtual device driver to open */
HVDD    rc;

rc = VDHOpenVDD(VDDName);



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 VDDNameis not found.
    *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 VDDNameis not found.
    *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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHOpenVIRQ

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.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);



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. 

#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);



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 "in service" (the ISR bit has been cleared) when the virtual device driver's EOI handler is called. The interface to the EOI handler is: 

VOID HOOKENTRY EOIHdlr(pcrf)
    ENTRY   pcrf - Pointer to client register frame
    EXIT    None
    USES    EAX, ECX, EDX, FS, GS, Flags
    CONTEXT DOS session-task




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: 

VOID HOOKENTRY IRETHdlr(pcrf)
     ENTRY   pcrf - Pointer to client register frame
     EXIT    None
     USES    EAX, ECX, EDX, FS, GS, Flags
     CONTEXT DOS session-task




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 OptionFlagby 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). VDHGetErrorshould be called to determine the nature of the problem. If IRQNumber, EOIHandler, IRETHandler, or OptionFlagare 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 "in service" (the ISR bit has been cleared) when the virtual device driver's EOI handler is called. The interface to the EOI handler is: 

VOID HOOKENTRY EOIHdlr(pcrf)
    ENTRY   pcrf - Pointer to client register frame
    EXIT    None
    USES    EAX, ECX, EDX, FS, GS, Flags
    CONTEXT DOS session-task


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: 

VOID HOOKENTRY IRETHdlr(pcrf)
     ENTRY   pcrf - Pointer to client register frame
     EXIT    None
     USES    EAX, ECX, EDX, FS, GS, Flags
     CONTEXT DOS session-task


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 OptionFlagby 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). VDHGetErrorshould be called to determine the nature of the problem. If IRQNumber, EOIHandler, IRETHandler, or OptionFlagare 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHPhysicalDisk

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function returns information about partitionable disks. 

#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);



VDHPhysicalDisk - Format

This function returns information about partitionable disks. 

#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);



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
VDHPHYD_GET_HANDLE Obtain a handle to use with the Category 9 IOCtls
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). VDHGetErrorshould be called to determine the nature of the problem. VDHGetErrorcan return the following error codes:

ERROR_ACCESS_DENIED
ERROR_INVALID_FUNCTION
ERROR_INVALID_HANDLE
ERROR_INVALID_PARAMETER
ERROR_LOCK_VIOLATION

If VDHPhysicalDiskis 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
VDHPHYD_GET_HANDLE Obtain a handle to use with the Category 9 IOCtls
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). VDHGetErrorshould be called to determine the nature of the problem. VDHGetErrorcan return the following error codes:

ERROR_ACCESS_DENIED
ERROR_INVALID_FUNCTION
ERROR_INVALID_HANDLE
ERROR_INVALID_PARAMETER
ERROR_LOCK_VIOLATION

If VDHPhysicalDiskis 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: 

    number:<null byte>

    Where:
          number       Specifies the partitionable disk (1-based) number in ASCII
          :            Must be present
          <null byte>  Specifies the byte of 0 for the ASCIIZ string

Notes: If the pointers passed by this function are allocated from the stack , then the SSToDSmacro 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHPopInt

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

VOID    ;
BOOL    rc;

rc = VDHPopInt();



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. 

#include mvdm.h

VOID    ;
BOOL    rc;

rc = VDHPopInt();



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHPopRegs

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function reverses the VDHPushRegsby popping the specified client registers into the Client Register Frame (CRF) from the client's stack. 

#include mvdm.h

FLAGS    RegFlag;  /*  Indicates which client registers to pop */
BOOL     rc;

rc = VDHPopRegs(RegFlag);



VDHPopRegs - Format

This function reverses the VDHPushRegsby popping the specified client registers into the Client Register Frame (CRF) from the client's stack. 

#include mvdm.h

FLAGS    RegFlag;  /*  Indicates which client registers to pop */
BOOL     rc;

rc = VDHPopRegs(RegFlag);



VDHPopRegs Parameter - RegFlag

RegFlag(FLAGS) Flag indicating which client registers to pop.

These flags can be "ORed" together to indicate more than one register. Possible values are:

VDHREG_AX Pop the AX register
VDHREG_BX Pop the BX register
VDHREG_CX Pop the CX register
VDHREG_DX Pop the DX register
VDHREG_SI Pop the SI register
VDHREG_DI Pop the DI register
VDHREG_BP Pop the BP register
VDHREG_SP Pop the SP register
VDHREG_DS Pop the DS register
VDHREG_ES Pop the ES register
VDHREG_SS Pop the SS register
VDHREG_FLAG Pop the Flags register
VDHREG_ALL Pop all the registers
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 RegFlagis invalid, a system halt occurs.



VDHPopRegs - Parameters

RegFlag(FLAGS) Flag indicating which client registers to pop.

These flags can be "ORed" together to indicate more than one register. Possible values are:

VDHREG_AX Pop the AX register
VDHREG_BX Pop the BX register
VDHREG_CX Pop the CX register
VDHREG_DX Pop the DX register
VDHREG_SI Pop the SI register
VDHREG_DI Pop the DI register
VDHREG_BP Pop the BP register
VDHREG_SP Pop the SP register
VDHREG_DS Pop the DS register
VDHREG_ES Pop the ES register
VDHREG_SS Pop the SS register
VDHREG_FLAG Pop the Flags register
VDHREG_ALL Pop all the registers
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 RegFlagis 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 RegFlagvalue to VDHPopRegsthat was used for the corresponding VDHPushRegscall. If the caller does not do this, the client stack can become damaged. This function always returns Successful when RegFlagis valid and the DOS session is in V86 mode because no data accesses below 1MB can cause a fault.



VDHPopRegs - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHPopStack

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function pops the data off the client's stack. 

#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);



VDHPopStack - Format

This function pops the data off the client's stack. 

#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);



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 NumBytesis 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 NumBytesis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHPopup

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function displays a message according to the Message ID, and gets a response from the user. 

#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);



VDHPopup - Format

This function displays a message according to the Message ID, and gets a response from the user. 

#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);



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)
VDHP_RETRY (0004H)
VDHP_IGNORE (0008H)
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 RespPtris filled in with actual response selected by the user.

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould 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)
VDHP_RETRY (0004H)
VDHP_IGNORE (0008H)
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 RespPtris filled in with actual response selected by the user.

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould 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 DosWriteto standard output (stdout) had been made. No prompt is displayed, and no user response is returned. ResponsePtris 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 ResponsePtris not used. "Retry" is the default action chosen for hard errors. If Retry is not allowed, "End the Program" is chosen as the default.



VDHPopup - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHPostEventSem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function posts an event semaphore. All the threads blocked on this semaphore will wake up. 

#include mvdm.h

HVDHSEM    EventSemHandle;  /*  Handle of an event semaphore */

VDHPostEventSem(EventSemHandle);



VDHPostEventSem - Format

This function posts an event semaphore. All the threads blocked on this semaphore will wake up. 

#include mvdm.h

HVDHSEM    EventSemHandle;  /*  Handle of an event semaphore */

VDHPostEventSem(EventSemHandle);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHPrintClose

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

HVDM    VDMHandle;  /*  DOS session handle */

VDHPrintClose(VDMHandle);



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. 

#include mvdm.h

HVDM    VDMHandle;  /*  DOS session handle */

VDHPrintClose(VDMHandle);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHPushFarCall

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function simulates a Far Call to V86 code as if a DOS program had executed a Far Call instruction. 

#include mvdm.h

FPFN    SegOffAddr;  /*  Address of V86 mode or protected mode code to call */
BOOL    rc;

rc = VDHPushFarCall(SegOffAddr);



VDHPushFarCall - Format

This function simulates a Far Call to V86 code as if a DOS program had executed a Far Call instruction. 

#include mvdm.h

FPFN    SegOffAddr;  /*  Address of V86 mode or protected mode code to call */
BOOL    rc;

rc = VDHPushFarCall(SegOffAddr);



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, VDHArmReturnHookis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHPushInt

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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 ninstruction. Any virtual device driver hooked on this interrupt with VDHInstallIntHookwill get control as expected. The VDHArmReturnHookservice 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.h

ULONG    Vector;  /*  Number of the interrupt vector to push */
BOOL     rc;

rc = VDHPushInt(Vector);



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 ninstruction. Any virtual device driver hooked on this interrupt with VDHInstallIntHookwill get control as expected. The VDHArmReturnHookservice 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.h

ULONG    Vector;  /*  Number of the interrupt vector to push */
BOOL     rc;

rc = VDHPushInt(Vector);



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 Vectoris 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 Vectoris 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHPushRegs

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

FLAGS    RegFlag;  /*  Flag indicating which client registers to push */
BOOL     rc;

rc = VDHPushRegs(RegFlag);



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. 

#include mvdm.h

FLAGS    RegFlag;  /*  Flag indicating which client registers to push */
BOOL     rc;

rc = VDHPushRegs(RegFlag);



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
VDHREG_BX Push the BX register
VDHREG_CX Push the CX register
VDHREG_DX Push the DX register
VDHREG_SI Push the SI register
VDHREG_DI Push the DI register
VDHREG_BP Push the BP register
VDHREG_SP Push the SP register
VDHREG_DS Push the DS register
VDHREG_ES Push the ES register
VDHREG_SS Push the SS register
VDHREG_FLAG Push the Flags register
VDHREG_ALL Push all the registers
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 RegFlagis 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
VDHREG_BX Push the BX register
VDHREG_CX Push the CX register
VDHREG_DX Push the DX register
VDHREG_SI Push the SI register
VDHREG_DI Push the DI register
VDHREG_BP Push the BP register
VDHREG_SP Push the SP register
VDHREG_DS Push the DS register
VDHREG_ES Push the ES register
VDHREG_SS Push the SS register
VDHREG_FLAG Push the Flags register
VDHREG_ALL Push all the registers
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 RegFlagis 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 RegFlagis valid and the DOS session is in V86 mode because no data accessed below 1MB can cause a fault .



VDHPushRegs - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHPushStack

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function pushes data onto the client's stack. 

#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);



VDHPushStack - Format

This function pushes data onto the client's stack. 

#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);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHPutSysValue

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function sets a system value. 

#include mvdm.h

ULONG    Index;  /*  Index of the system variable to set */
ULONG    Value;  /*  New value for the system variable */

VDHPutSysValue(Index, Value);



VDHPutSysValue - Format

This function sets a system value. 

#include mvdm.h

ULONG    Index;  /*  Index of the system variable to set */
ULONG    Value;  /*  New value for the system variable */

VDHPutSysValue(Index, Value);



VDHPutSysValue Parameter - Index

Index(ULONG) Index of the system value to set. System value indexes are defined in VDMM.INC and listed in 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 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHQueryFreePages

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

VOID     ;
ULONG    rc;

rc = VDHQueryFreePages();



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. 

#include mvdm.h

VOID     ;
ULONG    rc;

rc = VDHQueryFreePages();



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHQueryHookData

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function returns a pointer to the reference data created during the call to VDHAllocHook. 

#include mvdm.h

HHOOK    HookHandle;  /*  Hook handle from VDHAllocHook */
PVOID    rc;

rc = VDHQueryHookData(HookHandle);



VDHQueryHookData - Format

This function returns a pointer to the reference data created during the call to VDHAllocHook. 

#include mvdm.h

HHOOK    HookHandle;  /*  Hook handle from VDHAllocHook */
PVOID    rc;

rc = VDHQueryHookData(HookHandle);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHQueryLin

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

F16PVOID    Far16Addr;  /*  16:16 addressto be converted */
PVOID       rc;

rc = VDHQueryLin(Far16Addr);



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. 

#include mvdm.h

F16PVOID    Far16Addr;  /*  16:16 addressto be converted */
PVOID       rc;

rc = VDHQueryLin(Far16Addr);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHQueryKeyShift

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function is called by the virtual mouse device driver to query the keyboard shift state of a DOS session. 

#include mvdm.h

HVDM      VDMHandle;  /*  DOS session handle */
USHORT    rc;

rc = VDHQueryKeyShift(VDMHandle);



VDHQueryKeyShift - Format

This function is called by the virtual mouse device driver to query the keyboard shift state of a DOS session. 

#include mvdm.h

HVDM      VDMHandle;  /*  DOS session handle */
USHORT    rc;

rc = VDHQueryKeyShift(VDMHandle);



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
Left Shift 2
Ctrl 4
ALT 8
Left Ctrl 100
Left ALT 200
Right Ctrl 400
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
Left Shift 2
Ctrl 4
ALT 8
Left Ctrl 100
Left ALT 200
Right Ctrl 400
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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHQueryProperty

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function returns the current value of the specified DOS Setting. 

#include mvdm.h

PSZ      PropertyName;  /*  Pointer to a property name */
ULONG    rc;

rc = VDHQueryProperty(PropertyName);



VDHQueryProperty - Format

This function returns the current value of the specified DOS Setting. 

#include mvdm.h

PSZ      PropertyName;  /*  Pointer to a property name */
ULONG    rc;

rc = VDHQueryProperty(PropertyName);



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 0value 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 0value 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHQuerySel

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

PVOID    VirtAddress;  /*  0:32 virtual address */
SEL      rc;

rc = VDHQuerySel(VirtAddress);



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). 

#include mvdm.h

PVOID    VirtAddress;  /*  0:32 virtual address */
SEL      rc;

rc = VDHQuerySel(VirtAddress);



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.
    *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, VDHQuerySelneeds 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHQuerySem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function queries the state of an event or mutex semaphore. 

#include mvdm.h

HVDHSEM         SemHandle;    /*  Handle to an event or mutex semaphore */
PVDHSEMSTATE    SemStatePtr;  /*  Pointer to a VDHSEMSTATE data area */

VDHQuerySem(SemHandle, SemStatePtr);



VDHQuerySem - Format

This function queries the state of an event or mutex semaphore. 

#include mvdm.h

HVDHSEM         SemHandle;    /*  Handle to an event or mutex semaphore */
PVDHSEMSTATE    SemStatePtr;  /*  Pointer to a VDHSEMSTATE data area */

VDHQuerySem(SemHandle, SemStatePtr);



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: 

 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;




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: 

 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;


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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHQuerySysValue

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function queries a system value. 

#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);



VDHQuerySysValue - Format

This function queries a system value. 

#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);



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) VDHQuerySysValueindex values (as defined in VDMM.INC) and descriptions: 

Global Values        Ordinal  Type   Units         Range
_____________        _______  ____   _____         _____

VDHGSV_DAY              0     ULONG  days          1 < = x < = 31
VDHGSV_MONTH            1     ULONG  months        1 < = x < = 12
VDHGSV_YEAR             2     ULONG  years         1980 < = x < = MAXULONG
VDHGSV_DAYOFWEEK        3     ULONG  days          0 < = x < = 6
VDHGSV_HOUR             4     ULONG  hours         0 < = x < = 24
VDHGSV_MINUTE           5     ULONG  minutes       0 < = x < = 60
VDHGSV_SECOND           6     ULONG  seconds       0 < = x < = 60
VDHGSV_HUNDREDTH        7     ULONG  1/100S        0 < = x < = 100
VDHGSV_SECONDS1970      8     ULONG  seconds       0 < = x < = MAXULONG
VDHGSV_TIMEZONE         9     ULONG  minutes       0 < = x < = MAXULONG
VDHGSV_MSECSBOOT        10    ULONG  milliseconds  0 < = x < = MAXULONG
VDHGSV_TIMERINTERVAL    11    ULONG  milliseconds  0 < = x < = 1000
VDHGSV_DYNVARIATION     12    BOOL                 TRUE(nonzero)/FALSE(0)
VDHGSV_MAXWAIT          13    ULONG  seconds       0 < = x < = MAXULONG
VDHGSV_MINTIMESLICE     14    ULONG  milliseconds  0 < = x < = MAXULONG
VDHGSV_MAXTIMESLICE     15    ULONG  milliseconds  0 < = x < = MAXULONG
VDHGSV_YIELD            16    BOOL                 TRUE(nonzero)/FALSE(0)
VDHGSV_TCYIELD          17    BOOL                 TRUE(nonzero)/FALSE(0)
VDHGSV_VERMAJOR         18    ULONG                0 < = x < = MAXULONG
VDHGSV_VERMINOR         19    ULONG                0 < = x < = MAXULONG
VDHGSV_VERREVISION      20    CHAR                 0 < = x < = 255


Global Values        Ordinal  Type   Units         Range
_____________        _______  ____   _____         _____

VDHGSV_MACHINETYPE      21    ULONG                MACHINE_TYPE_
VDHGSV_BLACKHOLEADDR    22    PVOID  bytes         0 < = x < = MAXULONG
VDHGSV_BLACKHOLESIZE    23    ULONG  bytes         0 < = x < = MAXULONG
VDHGSV_FGNDSESSIONID    24    ULONG                0 < = x < = 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 < = x < MAXSESSIONS
VDHLSV_FOREGROUND     4100    BOOL                 TRUE(nonzero)/FALSE(0)
VDHLSV_RMSIZE         4101    ULONG  KB            0 < x < = 640
VDHLSV_CODEPAGEID     4102    ULONG                See DosGetCP
VDHLSV_PRIORITYCLASS  4103    ULONG                See VDHSetPriority
VDHLSV_PRIORITYLEVEL  4104    ULONG                See VDHSetPriority
VDHLSV_VPICBASE       4105    UCHAR[4]




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 VDHGetErrorreturns 0, then 0 is the correct value.

Failure If VDMHandleor Indexis 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) VDHQuerySysValueindex values (as defined in VDMM.INC) and descriptions: 

Global Values        Ordinal  Type   Units         Range
_____________        _______  ____   _____         _____

VDHGSV_DAY              0     ULONG  days          1 < = x < = 31
VDHGSV_MONTH            1     ULONG  months        1 < = x < = 12
VDHGSV_YEAR             2     ULONG  years         1980 < = x < = MAXULONG
VDHGSV_DAYOFWEEK        3     ULONG  days          0 < = x < = 6
VDHGSV_HOUR             4     ULONG  hours         0 < = x < = 24
VDHGSV_MINUTE           5     ULONG  minutes       0 < = x < = 60
VDHGSV_SECOND           6     ULONG  seconds       0 < = x < = 60
VDHGSV_HUNDREDTH        7     ULONG  1/100S        0 < = x < = 100
VDHGSV_SECONDS1970      8     ULONG  seconds       0 < = x < = MAXULONG
VDHGSV_TIMEZONE         9     ULONG  minutes       0 < = x < = MAXULONG
VDHGSV_MSECSBOOT        10    ULONG  milliseconds  0 < = x < = MAXULONG
VDHGSV_TIMERINTERVAL    11    ULONG  milliseconds  0 < = x < = 1000
VDHGSV_DYNVARIATION     12    BOOL                 TRUE(nonzero)/FALSE(0)
VDHGSV_MAXWAIT          13    ULONG  seconds       0 < = x < = MAXULONG
VDHGSV_MINTIMESLICE     14    ULONG  milliseconds  0 < = x < = MAXULONG
VDHGSV_MAXTIMESLICE     15    ULONG  milliseconds  0 < = x < = MAXULONG
VDHGSV_YIELD            16    BOOL                 TRUE(nonzero)/FALSE(0)
VDHGSV_TCYIELD          17    BOOL                 TRUE(nonzero)/FALSE(0)
VDHGSV_VERMAJOR         18    ULONG                0 < = x < = MAXULONG
VDHGSV_VERMINOR         19    ULONG                0 < = x < = MAXULONG
VDHGSV_VERREVISION      20    CHAR                 0 < = x < = 255


Global Values        Ordinal  Type   Units         Range
_____________        _______  ____   _____         _____

VDHGSV_MACHINETYPE      21    ULONG                MACHINE_TYPE_
VDHGSV_BLACKHOLEADDR    22    PVOID  bytes         0 < = x < = MAXULONG
VDHGSV_BLACKHOLESIZE    23    ULONG  bytes         0 < = x < = MAXULONG
VDHGSV_FGNDSESSIONID    24    ULONG                0 < = x < = 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 < = x < MAXSESSIONS
VDHLSV_FOREGROUND     4100    BOOL                 TRUE(nonzero)/FALSE(0)
VDHLSV_RMSIZE         4101    ULONG  KB            0 < x < = 640
VDHLSV_CODEPAGEID     4102    ULONG                See DosGetCP
VDHLSV_PRIORITYCLASS  4103    ULONG                See VDHSetPriority
VDHLSV_PRIORITYLEVEL  4104    ULONG                See VDHSetPriority
VDHLSV_VPICBASE       4105    UCHAR[4]


rc(ULONG) - returns

Success If the function is successful, it returns the value of the system variable. If the value is 0 and VDHGetErrorreturns 0, then 0 is the correct value.

Failure If VDMHandleor Indexis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHQueryVIRQ

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

HVDM     VDMHandle;  /*  IRQ handle from DOS session handle */
HIRQ     IRQHandle;  /*  IRQ handle from VDHOpenVIRQ */
ULONG    rc;

rc = VDHQueryVIRQ(VDMHandle, IRQHandle);



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. 

#include mvdm.h

HVDM     VDMHandle;  /*  IRQ handle from DOS session handle */
HIRQ     IRQHandle;  /*  IRQ handle from VDHOpenVIRQ */
ULONG    rc;

rc = VDHQueryVIRQ(VDMHandle, IRQHandle);



VDHQueryVIRQ Parameter - VDMHandle

VDMHandle(HVDM) IRQ handle from VDHOpenVIRQDOS 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
VPICQ_IN_SERVICE Queried IRQ is in service
VPICQ_VIRT_MASK Mask is turned ON for the queried IRQ
VPICQ_STAT_IRET_PENDING IRET is pending for the queried IRQ.

Failure If VDMHandleor IRQHandleis invalid, a system halt occurs.



VDHQueryVIRQ - Parameters

VDMHandle(HVDM) IRQ handle from VDHOpenVIRQDOS 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
VPICQ_IN_SERVICE Queried IRQ is in service
VPICQ_VIRT_MASK Mask is turned ON for the queried IRQ
VPICQ_STAT_IRET_PENDING IRET is pending for the queried IRQ.

Failure If VDMHandleor IRQHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHRaiseException

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.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);



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. 

#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);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHRead

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function reads bytes from a file or device previously opened by VDHOpen. 

#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);



VDHRead - Format

This function reads bytes from a file or device previously opened by VDHOpen. 

#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);



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. VDHGetErrorshould be called to determine the nature of the problem. If FileHandleis 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. VDHGetErrorshould be called to determine the nature of the problem. If FileHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHReadUBuf

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.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);



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. 

#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);



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.
VPM_PROT_WRITE Check for write.
VPM_FAULT_IF_SU_SET Fault, if supervisor pages.
VPM_FAULT_IF_RO Fault, if writing to read-only descriptor.
VPM_SEL_PRESENT Caller knows descriptor is present.
VPM_SEL_WRITEABLE Caller knows descriptor is writable.
VPM_SEL_IS_SS Selector is client's stack.
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, OffsetPointeris updated with the address of the fault. For selector faults, OffsetPointeris 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.
VPM_PROT_WRITE Check for write.
VPM_FAULT_IF_SU_SET Fault, if supervisor pages.
VPM_FAULT_IF_RO Fault, if writing to read-only descriptor.
VPM_SEL_PRESENT Caller knows descriptor is present.
VPM_SEL_WRITEABLE Caller knows descriptor is writable.
VPM_SEL_IS_SS Selector is client's stack.
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, OffsetPointeris updated with the address of the fault. For selector faults, OffsetPointeris 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHReallocPages

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function expands or shrinks a memory object. 

#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);



VDHReallocPages - Format

This function expands or shrinks a memory object. 

#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);



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). VDHGetErrorshould be called to determine the nature of the problem. If the memory object at ObjectAddresswas not allocated by VDHAllocPagesor VDHReallocPages, or if the NumPagesor Reservedparameters 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). VDHGetErrorshould be called to determine the nature of the problem. If the memory object at ObjectAddresswas not allocated by VDHAllocPagesor VDHReallocPages, or if the NumPagesor Reservedparameters 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 VDHAllocPagesis 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 VDHReallocPagesactivity, all pages in the allocation retain the same properties, that is, fixed, system, and physical.



VDHReallocPages - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHRegisterAPI

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.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);



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. 

#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);



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: 

VOID HOOKENTRY pfnHook(p,prcf)
     ENTRY     PVOID p-reserved
               PCRF pcrf-pointer to client register frame
     EXIT      None
     CONTEXT   DOS session-task

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): 

     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

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. 

     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

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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHRegisterDMAChannel

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

ULONG     DMAChannel;      /*  DMA channel */
PFNDMA    DMAHandlerFunc;  /*  The virtual device driver's DMA-handling routine */
BOOL      rc;

rc = VDHRegisterDMAChannel(DMAChannel, DMAHandlerFunc);



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. 

#include mvdm.h

ULONG     DMAChannel;      /*  DMA channel */
PFNDMA    DMAHandlerFunc;  /*  The virtual device driver's DMA-handling routine */
BOOL      rc;

rc = VDHRegisterDMAChannel(DMAChannel, DMAHandlerFunc);



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: 

 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)




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). VDHGetErrorshould 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: 

 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)


rc(BOOL) - returns

Success If the function is successful, it returns 1.

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHRegisterProperty

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function registers a virtual device driver property with the DOS Session Manager. 

#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);



VDHRegisterProperty - Format

This function registers a virtual device driver property with the DOS Session Manager. 

#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);



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
VDMP_INT 1-Integer. DD size, but only DW is valid
VDMP_ENUM 2-Enumeration
VDMP_STRING 3-ASCIIZ string
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
VDMP_ORD_KERNEL 1-ASCIIZ path of DOS kernel
VDMP_ORD_SHELL 2-ASCIIZ path of DOS_SHELL
VDMP_ORD_RMSIZE 3-Integer size of DOS box (128KB-640KB)
VDMP_ORD_FCB 4-Integer total FCBs
VDMP_ORD_FCB2 5-Integer FCBs immune to close LRUing
VDMP_ORD_BREAK 6-Boolean Break flag
VDMP_ORD_DOSDD 7-Multi-line string DOS_DEVICE
VDMP_ORD_VMBOOT 8-ASCIIZ string virtual machine boot drives
VDMP_ORD_VERSION 10-Multi-line string fake version entries
VDMP_ORD_DOS_UMB 11-Boolean flag. DOS_UMB
VDMP_ORD_DOS_HIGH 12-Boolean flag. DOS_HIGH
VDMP_ORD_LASTDRIVE 13-ASCIIZ DOS_LASTDRIVE
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.
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.
VDMP_ENUM DefaultValue is interpreted as a pointer to an ASCIIZ string.
VDMP_STRING DefaultValue is interpreted as a pointer to an ASCIIZ string.
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 >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: 

 typedef struct VPBOUND_s {
     USHORT  min;    // minimum allowed value
     USHORT  max;    // maximum allowed value
     USHORT  step;   // increment between values
 } VPBOUND;

typedef VPBOUND *PVPBOUND;

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 ("\ 0") 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: 

 #define VDHPROP_VALIDATE    0x00000000L
 #define VDHPROP_SET         0x00000001L

 ULONG EXPENTRY fnvdhrp (ULONG op, HVDM hvdm, ULONG cb, PSZ pch);

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. 

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.

op Operation to perform (enumeration):

VDHPROP_VALIDATE Validate property for any process. Only called for VDMP_ STRING and VDMP_MLSTR properties.
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
VDMPROP_INT Undefined
VDMPROP_ENUM Length of ASCIIZ string including NULL terminator
VDMPROP_STRING Length of ASCIIZ string including NULL terminator
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. VDHGetErrorshould 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
    *PropertyFlag or PropertyType are invalid
    *A VPBOUND structure has invalid contents
    *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
VDMP_INT 1-Integer. DD size, but only DW is valid
VDMP_ENUM 2-Enumeration
VDMP_STRING 3-ASCIIZ string
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
VDMP_ORD_KERNEL 1-ASCIIZ path of DOS kernel
VDMP_ORD_SHELL 2-ASCIIZ path of DOS_SHELL
VDMP_ORD_RMSIZE 3-Integer size of DOS box (128KB-640KB)
VDMP_ORD_FCB 4-Integer total FCBs
VDMP_ORD_FCB2 5-Integer FCBs immune to close LRUing
VDMP_ORD_BREAK 6-Boolean Break flag
VDMP_ORD_DOSDD 7-Multi-line string DOS_DEVICE
VDMP_ORD_VMBOOT 8-ASCIIZ string virtual machine boot drives
VDMP_ORD_VERSION 10-Multi-line string fake version entries
VDMP_ORD_DOS_UMB 11-Boolean flag. DOS_UMB
VDMP_ORD_DOS_HIGH 12-Boolean flag. DOS_HIGH
VDMP_ORD_LASTDRIVE 13-ASCIIZ DOS_LASTDRIVE
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.
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.
VDMP_ENUM DefaultValue is interpreted as a pointer to an ASCIIZ string.
VDMP_STRING DefaultValue is interpreted as a pointer to an ASCIIZ string.
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 >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: 

 typedef struct VPBOUND_s {
     USHORT  min;    // minimum allowed value
     USHORT  max;    // maximum allowed value
     USHORT  step;   // increment between values
 } VPBOUND;

typedef VPBOUND *PVPBOUND;

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 ("\ 0") 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: 

 #define VDHPROP_VALIDATE    0x00000000L
 #define VDHPROP_SET         0x00000001L

 ULONG EXPENTRY fnvdhrp (ULONG op, HVDM hvdm, ULONG cb, PSZ pch);

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. 

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.

op Operation to perform (enumeration):

VDHPROP_VALIDATE Validate property for any process. Only called for VDMP_ STRING and VDMP_MLSTR properties.
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
VDMPROP_INT Undefined
VDMPROP_ENUM Length of ASCIIZ string including NULL terminator
VDMPROP_STRING Length of ASCIIZ string including NULL terminator
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. VDHGetErrorshould 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
    *PropertyFlag or PropertyType are invalid
    *A VPBOUND structure has invalid contents
    *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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHRegisterVDD

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function registers virtual device driver entry points for use by other virtual device drivers (through VDHOpenVDDand VDHRequestVDD), and by OS/2 applications (through DosOpenVDDand DosRequestVDD). 

#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);



VDHRegisterVDD - Format

This function registers virtual device driver entry points for use by other virtual device drivers (through VDHOpenVDDand VDHRequestVDD), and by OS/2 applications (through DosOpenVDDand DosRequestVDD). 

#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);



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 DosReqFcnis: 

 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




VDHRegisterVDD Parameter - VDDReqFcn

VDDReqFcn(PFNDEVREQ) Function used by VDHRequestVDD. NULL, if none.

The interface for the VDDReqFcnis: 

 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




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 DosReqFcnis: 

 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


VDDReqFcn(PFNDEVREQ) Function used by VDHRequestVDD. NULL, if none.

The interface for the VDDReqFcnis: 

 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


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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHReleaseCodePageFont

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

PVOID    FontPtr;  /*  Pointer returned by VDHGetCodePageFont */

VDHReleaseCodePageFont(FontPtr);



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. 

#include mvdm.h

PVOID    FontPtr;  /*  Pointer returned by VDHGetCodePageFont */

VDHReleaseCodePageFont(FontPtr);



VDHReleaseCodePageFont Parameter - FontPtr

FontPtr(PVOID) Pointer returned in FontAddressby VDHGetCodePageFont.



VDHReleaseCodePageFont - Return Value

Success If the function is successful, it returns nothing.

Failure If FontPtris not valid, a system halt occurs.



VDHReleaseCodePageFont - Parameters

FontPtr(PVOID) Pointer returned in FontAddressby VDHGetCodePageFont.

Success If the function is successful, it returns nothing.

Failure If FontPtris 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHReleaseMutexSem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function releases the ownership of a mutex semaphore. If the request count becomes 0 (zero), the highest priority semaphore is awakened. 

#include mvdm.h

HVDHSEM    MutexSemHandle;  /*  Handle of the semaphore to be released */

VDHReleaseMutexSem(MutexSemHandle);



VDHReleaseMutexSem - Format

This function releases the ownership of a mutex semaphore. If the request count becomes 0 (zero), the highest priority semaphore is awakened. 

#include mvdm.h

HVDHSEM    MutexSemHandle;  /*  Handle of the semaphore to be released */

VDHReleaseMutexSem(MutexSemHandle);



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 MutexSemHandleis released.

Failure If the virtual device driver that called VDHReleaseMutexSemis not the owner of the semaphore to be released, or if MutexSemHandleinvalid, 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 MutexSemHandleis released.

Failure If the virtual device driver that called VDHReleaseMutexSemis not the owner of the semaphore to be released, or if MutexSemHandleinvalid, 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHRemoveFaultHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function removes the page fault handler hook for the specified DOS session page range. 

#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);



VDHRemoveFaultHook - Format

This function removes the page fault handler hook for the specified DOS session page range. 

#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);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHRemoveIOHook

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function must be called with StartingPortand NumPortsto 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.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);



VDHRemoveIOHook - Format

This function must be called with StartingPortand NumPortsto 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.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);



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 IOPortHookEntryis invalid or if StartingPortor NumPortsare 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 IOPortHookEntryis invalid or if StartingPortor NumPortsare 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 IOPortHookis in instance data, the address passed VDHInstallIOHookmust be the same address passed to VDHRemoveIOHookor VDHSetIOHookState.



VDHRemoveIOHook - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHReportPeek

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

ULONG    PeekWeight;  /*  Value to add to the idle counter */

VDHReportPeek(PeekWeight);



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. 

#include mvdm.h

ULONG    PeekWeight;  /*  Value to add to the idle counter */

VDHReportPeek(PeekWeight);



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 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHRequestMutexSem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

HVDHSEM    MutexSemHandle;  /*  Mutex semaphore handle */
ULONG      Timeout;         /*  Timeout (in milliseconds) */
BOOL       rc;

rc = VDHRequestMutexSem(MutexSemHandle, Timeout);



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. 

#include mvdm.h

HVDHSEM    MutexSemHandle;  /*  Mutex semaphore handle */
ULONG      Timeout;         /*  Timeout (in milliseconds) */
BOOL       rc;

rc = VDHRequestMutexSem(MutexSemHandle, Timeout);



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). VDHGetErrorshould 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). VDHGetErrorshould 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHRequestVDD

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.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);



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. 

#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);



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). VDHGetErrorshould be called to determine the nature of the problem. If VDDHandleor VDMHandleis 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). VDHGetErrorshould be called to determine the nature of the problem. If VDDHandleor VDMHandleis 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 VDHRequestVDDprocedure 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 VDHSetErrorwhen 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHReservePages

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function reserves a range of linear addresses for later use with VDHMapPagesor VDHAllocPages. A reserved area cannot contain a mixture of pages set by VDHMapPagesand VDHAllocPages, but it can be used successively with either one. 

#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);



VDHReservePages - Format

This function reserves a range of linear addresses for later use with VDHMapPagesor VDHAllocPages. A reserved area cannot contain a mixture of pages set by VDHMapPagesand VDHAllocPages, but it can be used successively with either one. 

#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);



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). VDHGetErrorshould be called to determine the nature of the problem. If StartingAddressor NumPagesis 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). VDHGetErrorshould be called to determine the nature of the problem. If StartingAddressor NumPagesis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHResetEventSem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function resets an event semaphore. 

#include mvdm.h

HVDHSEM    EventSemHandle;  /*  Handle to the event semaphore to be reset */

VDHResetEventSem(EventSemHandle);



VDHResetEventSem - Format

This function resets an event semaphore. 

#include mvdm.h

HVDHSEM    EventSemHandle;  /*  Handle to the event semaphore to be reset */

VDHResetEventSem(EventSemHandle);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHSeek

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function seeks to a specified position within a file previously opened by VDHOpen. 

#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);



VDHSeek - Format

This function seeks to a specified position within a file previously opened by VDHOpen. 

#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);



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
VDHSK_CURRENT_POSITION Move file-pointer relative to its current position
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. VDHGetErrorshould be called to determine the nature of the problem. If FileHandleis 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
VDHSK_CURRENT_POSITION Move file-pointer relative to its current position
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. VDHGetErrorshould be called to determine the nature of the problem. If FileHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHSendVEOI

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

HIRQ    IRQHandle;  /*  IRQ handle */

VDHSendVEOI(IRQHandle);



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. 

#include mvdm.h

HIRQ    IRQHandle;  /*  IRQ handle */

VDHSendVEOI(IRQHandle);



VDHSendVEOI Parameter - IRQHandle

IRQHandle(HIRQ) IRQ handle.



VDHSendVEOI - Return Value

Success If the function was successful, it returns nothing.

Failure If IRQHandleis invalid, a system halt occurs.



VDHSendVEOI - Parameters

IRQHandle(HIRQ) IRQ handle.

Success If the function was successful, it returns nothing.

Failure If IRQHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHSetDosDevice

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function links a DOS device driver into the chain of DOS device drivers for a DOS session. 

#include mvdm.h

VPDOSDDTYPE    vpDosDD;  /*  V86 FAR address of the DOS device driver header */
BOOL           rc;

rc = VDHSetDosDevice(vpDosDD);



VDHSetDosDevice - Format

This function links a DOS device driver into the chain of DOS device drivers for a DOS session. 

#include mvdm.h

VPDOSDDTYPE    vpDosDD;  /*  V86 FAR address of the DOS device driver header */
BOOL           rc;

rc = VDHSetDosDevice(vpDosDD);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHSetError

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function sets the error code for return by VDHGetError. 

#include mvdm.h

ULONG    ErrorCode;  /*  Error code to set */

VDHSetError(ErrorCode);



VDHSetError - Format

This function sets the error code for return by VDHGetError. 

#include mvdm.h

ULONG    ErrorCode;  /*  Error code to set */

VDHSetError(ErrorCode);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHSetFlags

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function sets the DOS session's Flags Register to specified values. 

#include mvdm.h

ULONG    FlagValue;  /*  DOS session flag value */

VDHSetFlags(FlagValue);



VDHSetFlags - Format

This function sets the DOS session's Flags Register to specified values. 

#include mvdm.h

ULONG    FlagValue;  /*  DOS session flag value */

VDHSetFlags(FlagValue);



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 VDHArmSTIHookworks 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHSetIOHookState

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function is used to enable and disable I/O port trapping for a range of ports. 

#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);



VDHSetIOHookState - Format

This function is used to enable and disable I/O port trapping for a range of ports. 

#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);



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.
FALSE (0). Disable I/O hooks.



VDHSetIOHookState - Return Value

Success If the function was successful, it returns nothing.

Failure If IOPortHookis invalid, or if StartingPortor NumPortsare out of range, or if StartingPortand NumPortsoverlap a range of ports previously marked as VDHIIH_ALWAYS_TRAPby 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.
FALSE (0). Disable I/O hooks.

Success If the function was successful, it returns nothing.

Failure If IOPortHookis invalid, or if StartingPortor NumPortsare out of range, or if StartingPortand NumPortsoverlap a range of ports previously marked as VDHIIH_ALWAYS_TRAPby 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 IOPortHookis in instance data, the address passed to VDHInstallIOHookmust be the same address passed to VDHRemoveIOHookor 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHSetPriority

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function adjusts a DOS session's scheduler priority class and level. Priority levels within each priority class range from 0-31. 

#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);



VDHSetPriority - Format

This function adjusts a DOS session's scheduler priority class and level. Priority levels within each priority class range from 0-31. 

#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);



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 Classcomponent of ActionClassFlagindicates the class to which the DOS session should be changed. The Actioncomponent of the ActionClassFlagallows the virtual device driver to manage when the priority is changed, and when to start, end, or continue use of the class. See "Notes" under Purpose.

The value of the Classcomponent can be one of the following:

VDHSP_TIME_CRITICAL Highest priority
VDHSP_SERVER Highest priority
VDHSP_REGULAR Highest priority
VDHSP_IDLE Lowest priority
VDHSP_NO_CHANGE Do not change the DOS session's class

The value of the Actioncomponent can be one of the following:

VDHSP_START_USE Start use of a class
VDHSP_CONTINUE_USE Continue use of a class
VDHSP_END_USE End use of a class
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 VDMHandleor ActionClassFlagare 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 Classcomponent of ActionClassFlagindicates the class to which the DOS session should be changed. The Actioncomponent of the ActionClassFlagallows the virtual device driver to manage when the priority is changed, and when to start, end, or continue use of the class. See "Notes" under Purpose.

The value of the Classcomponent can be one of the following:

VDHSP_TIME_CRITICAL Highest priority
VDHSP_SERVER Highest priority
VDHSP_REGULAR Highest priority
VDHSP_IDLE Lowest priority
VDHSP_NO_CHANGE Do not change the DOS session's class

The value of the Actioncomponent can be one of the following:

VDHSP_START_USE Start use of a class
VDHSP_CONTINUE_USE Continue use of a class
VDHSP_END_USE End use of a class
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 VDMHandleor ActionClassFlagare 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 NewPriorityis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHSetVIRR

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

HVDM    VDMHandle;  /*  DOS session handle */
HIRQ    IRQHandle;  /*  Handle from VDHOpenVIRQ */

VDHSetVIRR(VDMHandle, IRQHandle);



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. 

#include mvdm.h

HVDM    VDMHandle;  /*  DOS session handle */
HIRQ    IRQHandle;  /*  Handle from VDHOpenVIRQ */

VDHSetVIRR(VDMHandle, IRQHandle);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHSetVPMExcept

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function sets the current value in the protected-mode exception table. 

#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);



VDHSetVPMExcept - Format

This function sets the current value in the protected-mode exception table. 

#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);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHSetVPMIntVector

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

ULONG    Vector;          /*  Interrupt vector number */
FPFN     HandlerAddress;  /*  Far32 handler address */
BYTE     Flag;            /*  Flag. */
BOOL     rc;

rc = VDHSetVPMIntVector(Vector, HandlerAddress,
       Flag);



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. 

#include mvdm.h

ULONG    Vector;          /*  Interrupt vector number */
FPFN     HandlerAddress;  /*  Far32 handler address */
BYTE     Flag;            /*  Flag. */
BOOL     rc;

rc = VDHSetVPMIntVector(Vector, HandlerAddress,
       Flag);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHSwitchToVPM

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function switches the current DOS session into protected mode. This assumes that the appropriate initializations have already been performed. 

#include mvdm.h

VOID    ;

VDHSwitchToVPM();



VDHSwitchToVPM - Format

This function switches the current DOS session into protected mode. This assumes that the appropriate initializations have already been performed. 

#include mvdm.h

VOID    ;

VDHSwitchToVPM();



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHSwitchToV86

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function switches the current DOS session to V86 mode. 

#include mvdm.h

VOID    ;

VDHSwitchToV86();



VDHSwitchToV86 - Format

This function switches the current DOS session to V86 mode. 

#include mvdm.h

VOID    ;

VDHSwitchToV86();



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHThawVDM

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function reverses the effect of VDHFreezeVDM. The specified DOS session is allowed to run when the freeze count becomes 0 (zero). 

#include mvdm.h

HVDM    VDMHandle;  /*  Handle to the DOS session to thaw */

VDHThawVDM(VDMHandle);



VDHThawVDM - Format

This function reverses the effect of VDHFreezeVDM. The specified DOS session is allowed to run when the freeze count becomes 0 (zero). 

#include mvdm.h

HVDM    VDMHandle;  /*  Handle to the DOS session to thaw */

VDHThawVDM(VDMHandle);



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 VDMHandleis 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 VDMHandleis 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 VDHFreezeVDMfor a full discussion of freeze counting.



VDHThawVDM - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHUnlockMem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function reverses the effect of VDHLockMem, unlocking a previously locked area of memory. 

#include mvdm.h

HLOCK    LockHandle;  /*  Lock handle from VDHLockMem */

VDHUnlockMem(LockHandle);



VDHUnlockMem - Format

This function reverses the effect of VDHLockMem, unlocking a previously locked area of memory. 

#include mvdm.h

HLOCK    LockHandle;  /*  Lock handle from VDHLockMem */

VDHUnlockMem(LockHandle);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHUnreservePages

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

PVOID    StartingAddress;  /*  Starting address of the region to unreserve */
ULONG    NumPages;         /*  Size of the region to unreserve, in pages */

VDHUnreservePages(StartingAddress, NumPages);



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. 

#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);



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, StartingAddressmust match a previous VDHReservePagescall.



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 StartingAddressor NumPagesis 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, StartingAddressmust match a previous VDHReservePagescall.

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 StartingAddressor NumPagesis 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: StartingAddressmust be less than 110000H(1MB+64KB) and must be page -aligned. Additionally, StartingAddressmust match a previous call to VDHReservePages. NumPagesmust match the corresponding parameter to a previous call to VDHReservePages.



VDHUnreservePages - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHWaitEventSem

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function is used to wait on an event semaphore. If the semaphore is posted, it will return immediately. 

#include mvdm.h

HVDHSEM    EventSemHandle;  /*  Event semaphore handle */
ULONG      Timeout;         /*  Timeout (in milliseconds) */
BOOL       rc;

rc = VDHWaitEventSem(EventSemHandle, Timeout);



VDHWaitEventSem - Format

This function is used to wait on an event semaphore. If the semaphore is posted, it will return immediately. 

#include mvdm.h

HVDHSEM    EventSemHandle;  /*  Event semaphore handle */
ULONG      Timeout;         /*  Timeout (in milliseconds) */
BOOL       rc;

rc = VDHWaitEventSem(EventSemHandle, Timeout);



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). VDHGetErrorshould be called to determine the nature of the problem. If EventSemHandleis 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). VDHGetErrorshould be called to determine the nature of the problem. If EventSemHandleis 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 Timeoutis 0 (zero), the caller will not block; however, ERROR_TIMEOUT is returned. If Timeoutis -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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHWaitVIRRs

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function waits until any virtual interrupt is simulated to the current DOS session. 

#include mvdm.h

HHOOK    PostInFcnHook;  /*  Hook handle */
BOOL     rc;

rc = VDHWaitVIRRs(PostInFcnHook);



VDHWaitVIRRs - Format

This function waits until any virtual interrupt is simulated to the current DOS session. 

#include mvdm.h

HHOOK    PostInFcnHook;  /*  Hook handle */
BOOL     rc;

rc = VDHWaitVIRRs(PostInFcnHook);



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 VDHWakeVIRRscall, 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 VDHWakeVIRRscall, 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHWakeIdle

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.h

HVDM    VDMHandle;  /*  Handle to the DOS session to wake up */

VDHWakeIdle(VDMHandle);



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. 

#include mvdm.h

HVDM    VDMHandle;  /*  Handle to the DOS session to wake up */

VDHWakeIdle(VDMHandle);



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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHWakeVIRRs

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function wakes up a DOS session that is waiting with the VDHWaitVIRRsservice. See VDHWaitVIRRsfor a full description of the use of this function. 

#include mvdm.h

HVDM    VDMHandle;  /*  Handle of the DOS session to wake up */

VDHWakeVIRRs(VDMHandle);



VDHWakeVIRRs - Format

This function wakes up a DOS session that is waiting with the VDHWaitVIRRsservice. See VDHWaitVIRRsfor a full description of the use of this function. 

#include mvdm.h

HVDM    VDMHandle;  /*  Handle of the DOS session to wake up */

VDHWakeVIRRs(VDMHandle);



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 VDMHandleis 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 VDMHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHWrite

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function writes bytes to a file or device previously opened by VDHOpen . 

#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);



VDHWrite - Format

This function writes bytes to a file or device previously opened by VDHOpen . 

#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);



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. VDHGetErrorshould be called to determine the nature of the problem. If FileHandleis 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. VDHGetErrorshould be called to determine the nature of the problem. If FileHandleis 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHWriteUBuf

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

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.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);



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. 

#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);



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.
VPM_PROT_WRITE Check for write.
VPM_FAULT_IF_SU_SET Fault, if supervisor pages.
VPM_FAULT_IF_RO Fault, if writing to read-only descriptor.
VPM_SEL_PRESENT Caller knows descriptor is present.
VPM_SEL_WRITEABLE Caller knows descriptor is writable.
VPM_SEL_IS_SS Selector is client's stack.
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, OffsetPointeris updated with the address of the fault. For Selector Faults, OffsetPointerremains 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.
VPM_PROT_WRITE Check for write.
VPM_FAULT_IF_SU_SET Fault, if supervisor pages.
VPM_FAULT_IF_RO Fault, if writing to read-only descriptor.
VPM_SEL_PRESENT Caller knows descriptor is present.
VPM_SEL_WRITEABLE Caller knows descriptor is writable.
VPM_SEL_IS_SS Selector is client's stack.
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, OffsetPointeris updated with the address of the fault. For Selector Faults, OffsetPointerremains 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: 

Format
Parameters 
Return Codes 
Purpose 
Glossary



VDHYield

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary

This function yields the processor to any other thread of equal or higher priority. 

#include mvdm.h

BOOL    OptionFlag;  /*  Yield options */

VDHYield(OptionFlag);



VDHYield - Format

This function yields the processor to any other thread of equal or higher priority. 

#include mvdm.h

BOOL    OptionFlag;  /*  Yield options */

VDHYield(OptionFlag);



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 OptionFlagis VDH_YIELD_TIME_CRITICAL, and no time-critical thread is able to run, the caller keeps the CPU.



VDHYield - Topics

Select an item: 

Format
Parameters 
Return Codes 
Purpose 
Glossary
Retrieved from "https://www.edm2.com/index.php?title=VDDR/2_-_C_Language_Virtual_DevHlp_Services&oldid=27325"