By IBM

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

Assembler Language Syntax

This appendix categorizes the assembler language versions of all virtual DevHlp services in following list and in subsequent sections. These APIs are counterparts of the C language services listed in C Language Virtual DevHlp Services.

A detailed description of each function follows the #Virtual DevHlp Services by Category.

Function	Type
#VDHAllocBlock	byte-granular memory management service
#VDHAllocDMABuffer	DMA service
#VDHAllocDOSMem	byte-granular memory management service
#VDHAllocHook	hook management service
#VDHAllocMem	byte-granular memory management service
#VDHAllocPages	page-granular memory management service
#VDHArmBPHook	hook management service
#VDHArmContextHook	hook management service
#VDHArmReturnHook	hook management service
#VDHArmSTIHook	hook management service
#VDHArmTimerHook	timer service
#VDHArmVPMBPHook	DPMI service
#VDHBeginUseVPMStack	DPMI service
#VDHCallOutDMA	DMA service
#VDHChangeVPMIF	DPMI service
#VDHCheckPagePerm	DPMI service
#VDHCheckVPMIntVector	DPMI service
#VDHClearVIRR	virtual interrupt service
#VDHClose	file or device I/O service
#VDHCloseVDD	inter-device communication service
#VDHCloseVIRQ	virtual interrupt service
#VDHCopyMem	byte-granular memory management service
#VDHCreateBlockPool	byte-granular memory management service
#VDHCreateSel	GDT selector service
#VDHCreateSem	semaphore service
#VDHDecodeProperty	DOS settings service
#VDHDestroyBlockPool	byte-granular memory management service
#VDHDestroySel	GDT selector service
#VDHDestroySem	semaphore service
#VDHDevBeep	miscellaneous virtual DevHlp service
#VDHDevIOCtl	file or device I/O service
#VDHDisarmTimerHook	timer service
#VDHEndUseVPMStack	DPMI service
#VDHEnumerateVDMs	miscellaneous virtual DevHlp service
#VDHExchangeMem	byte-granular memory management service
#VDHFindFreePages	page-granular memory management service
#VDHFreeBlock	byte-granular memory management service
#VDHFreeDMABuffer	DMA service
#VDHFreeHook	hook management service
#VDHFreeMem	byte-granular memory management service
#VDHFreePages	page-granular memory management service
#VDHFreezeVDM	DOS session control service
#VDHGetCodePageFont	miscellaneous virtual DevHlp service
#VDHGetDirtyPageInfo	page-granular memory management service
#VDHGetError	miscellaneous virtual DevHlp service
#VDHGetFlags	miscellaneous virtual DevHlp service
#VDHGetSelBase	DPMI service
#VDHGetVPMExcept	DPMI service
#VDHGetVPMIntVector	DPMI service
#VDHHaltSystem	DOS session control service
#VDHHandleFromPID	miscellaneous virtual DevHlp service
#VDHHandleFromSGID	miscellaneous virtual DevHlp service
#VDHInstallFaultHook	page-granular memory management service
#VDHInstallIntHook	hook management service
#VDHInstallIOHook	hook management service
#VDHInstallUserHook	hook management service
#VDHIsVDMFrozen	DOS session control service
#VDHKillVDM	DOS session control service
#VDHLockMem	memory-locking memory management service
#VDHMapPages	page-granular memory management service
#VDHOpen	file or device I/O service
#VDHOpenPDD	inter-device communication service
#VDHOpenVDD	inter-device communication service
#VDHOpenVIRQ	virtual interrupt service
#VDHPhysicalDisk	file or device I/O service
#VDHPopInt	v8086 stack manipulation service
#VDHPopRegs	v8086 stack manipulation service
#VDHPopStack	v8086 stack manipulation service
#VDHPopup	miscellaneous virtual DevHlp service
#VDHPostEventSem	semaphore service
#VDHPrintClose	parallel port and printer service
#VDHPushFarCall	v8086 stack manipulation service
#VDHPushInt	v8086 stack manipulation service
#VDHPushRegs	v8086 stack manipulation service
#VDHPushStack	v8086 stack manipulation service
#VDHPutSysValue	miscellaneous virtual DevHlp service
#VDHQueryFreePages	page-granular memory management service
#VDHQueryHookData	hook management service
#VDHQueryLin	miscellaneous virtual DevHlp service
#VDHQueryKeyShift	keyboard service
#VDHQueryProperty	DOS settings service
#VDHQuerySel	GDT selector service
#VDHQuerySem	semaphore service
#VDHQuerySysValue	miscellaneous virtual DevHlp service
#VDHQueryVIRQ	virtual interrupt service
#VDHRaiseException	DPMI service
#VDHRead	file or device I/O service
#VDHReadUBuf	DPMI service
#VDHReallocPages	page-granular memory management service
#VDHRegisterAPI	Register API handler
#VDHRegisterDMAChannel	DMA service
#VDHRegisterProperty	DOS settings service
#VDHRegisterVDD	inter-device communication service
#VDHReleaseCodePageFont	miscellaneous virtual DevHlp service
#VDHReleaseMutexSem	semaphore service
#VDHRemoveFaultHook	page-granular memory management service
#VDHRemoveIOHook	hook management service
#VDHReportPeek	idle DOS application management service
#VDHRequestMutexSem	semaphore service
#VDHRequestVDD	inter-device communication service
#VDHReservePages	page-granular memory management service
#VDHResetEventSem	semaphore service
#VDHSeek	file or device I/O service
#VDHSendVEOI	virtual interrupt service
#VDHSetDosDevice	miscellaneous virtual DevHlp service
#VDHSetError	miscellaneous virtual DevHlp service
#VDHSetFlags	miscellaneous virtual DevHlp service
#VDHSetIOHookState	hook management service
#VDHSetPriority	DOS session control service
#VDHSetVIRR	virtual interrupt service
#VDHSetVPMExcept	DPMI service
#VDHSetVPMIntVector	DPMI service
#VDHSwitchToVPM	DPMI service
#VDHSwitchToV86	DPMI service
#VDHThawVDM	DOS session control service
#VDHUnlockMem	memory-locking memory management service
#VDHUnreservePages	page-granular memory management service
#VDHWaitEventSem	semaphore service
#VDHWaitVIRRs	virtual interrupt service
#VDHWakeIdle	idle DOS application management service
#VDHWakeVIRRs	virtual interrupt service
#VDHWrite	file or device I/O service
#VDHWriteUBuf	DPMI service
#VDHYield	DOS session control service

Virtual DevHlp Services by Category

Virtual DevHlp services can be divided into categories based on the type of service the virtual DevHlp provides. These categories are:

DMA Services

Function	Type
#VDHAllocDMABuffer	Allocate DMA buffer
#VDHCallOutDMA	Call virtual DMA device driver
#VDHFreeDMABuffer	Free DMA buffer
#VDHRegisterDMAChannel	Register DMA channel

DOS Session Control Services

Function	Type
#VDHFreezeVDM	Freeze DOS session
#VDHHaltSystem	Cause system halt
#VDHIsVDMFrozen	Determine if DOS session is frozen
#VDHKillVDM	Terminate DOS session
#VDHSetPriority	Adjust DOS session scheduler priority
#VDHThawVDM	Allow frozen DOS session to resume executing
#VDHYield	Yield the processor.

DOS Settings Services

Function	Type
#VDHDecodeProperty	Decode property string
#VDHQueryProperty	Query virtual device driver property value
#VDHRegisterProperty	Register virtual device driver property

DPMI Services

Function	Type
#VDHArmVPMBPHook	Obtain address of DOS session protected-mode breakpoint
#VDHBeginUseVPMStack	Begin using DOS session protected-mode stack
#VDHChangeVPMIF	Change virtual Interrupt Flag (IF)
#VDHCheckPagePerm	Check Ring 3 page permissions
#VDHCheckVPMIntVector	Determine if DOS session protected-mode handler exists
#VDHEndUseVPMStack	End use of DOS session protected-mode stack
#VDHGetSelBase	Get flat base address
#VDHGetVPMExcept	Get DOS session protected-mode exception vector
#VDHGetVPMIntVector	Return DOS session protected-mode interrupt vector
#VDHRaiseException	Raise an exception to a DOS session
#VDHReadUBuf	Read from protected-mode address space
#VDHSetVPMExcept	Set DOS session protected-mode exception vector
#VDHSetVPMIntVector	Set DOS session protected-mode interrupt vector
#VDHSwitchToVPM	Switch DOS session to protected mode
#VDHSwitchToV86	Switch DOS session to V86 mode
#VDHWriteUBuf	Write to protected-mode address space

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

File or Device I/O Services

Function	Type
#VDHClose	Close a file handle
#VDHDevIOCtl	Issue device-specific commands
#VDHOpen	Open a file or device
#VDHPhysicalDisk	Get information about partitionable disks
#VDHRead	Read bytes from file or device
#VDHSeek	Move read or write file pointer for a handle
#VDHWrite	Write bytes to file or device

GDT Selector Services

Function	Type
#VDHCreateSel	Create GDT selector to map a linear range
#VDHDestroySel	Destroy GDT selector
#VDHQuerySel	Get selector for data or stack address

Hook Management Services

Function	Type
#VDHAllocHook	Allocate hooks needed for interrupt simulation
#VDHArmBPHook	Obtain address of V86 breakpoint
#VDHArmContextHook	Set local or global context hook
#VDHArmReturnHook	Set handler to receive control
#VDHArmSTIHook	Set handler to receive control
#VDHFreeHook	Disarm and free hook
#VDHInstallIntHook	Set handler for V86 interrupt
#VDHInstallIOHook	Install I/O port hooks
#VDHInstallUserHook	Install handler for DOS session event
#VDHQueryHookData	Returns pointer to hook reference data
#VDHRemoveIOHook	Remove hooks for PIC I/O ports
#VDHSetIOHookState	Enable/disable I/O port trapping

Idle DOS Application Management Services

Function	Type
#VDHReportPeek	Report DOS session polling activity
#VDHWakeIdle	Wake up DOS session

Note: The services above indicate when a DOS application appears to be idle, and when activity exists that could make the DOS application busy.

Inter-Device Communication Services

DevHlp services

Function	Type
#VDHCloseVDD	Close virtual device driver
#VDHOpenPDD	Open physical device driver
#VDHOpenVDD	Open virtual device driver
#VDHRegisterVDD	Register virtual device driver entry points
#VDHRequestVDD	Issue request for virtual device driver operation

Keyboard Services

Function	Type
#VDHQueryKeyShift	Query keyboard shift state

Memory Management Services

There are three sub-categories of the memory management virtual DevHlp services. The first two are used for the granularity of the memory allocation unit, the third category is used for memory-locking services.

Byte-Granular Memory Management Services

Function	Type
#VDHAllocBlock	Allocate block from memory block pool
#VDHAllocDOSMem	Allocate block of memory from DOS area
#VDHAllocMem	Allocate small amount of memory
#VDHCopyMem	Copy from one linear memory address to another
#VDHCreateBlockPool	Create memory block pool
#VDHDestroyBlockPool	Destroy memory block pool
#VDHExchangeMem	Exchange contents of two linear memory regions
#VDHFreeBlock	Free block of memory
#VDHFreeMem	Free memory

Page-Granular Memory Management Services

Function	Type
#VDHAllocPages	Allocate page-aligned memory object
#VDHFindFreePages	Find largest available linear memory
#VDHFreePages	Free memory object
#VDHGetDirtyPageInfo	Return status of dirty bits
#VDHInstallFaultHook	Install page fault handler
#VDHMapPages	Map specified linear address
#VDHQueryFreePages	Return amount of free virtual memory
#VDHReallocPages	Reallocate memory object
#VDHRemoveFaultHook	Remove page fault handler
#VDHReservePages	Reserve range of linear addresses
#VDHUnreservePages	Unreserve range of linear addresses

Memory-Locking Memory Management Services

Function	Type
#VDHLockMem	Verify access or lock memory
#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

Mapping to another linear address

Mapping to black holes (don't care) pages

Mapping to invalid (unmapped) pages

Note: Virtual device drivers can also request smaller memory allocations from the kernel heap, which is global and fixed. Small, fixed size block services are available to speed up frequent allocations and freeing of memory. For a particular block size, a pool of blocks is maintained and the requirements are met by taking off a block from the block pool.

Miscellaneous Virtual DevHlp Services

Function	Type
#VDHDevBeep	Device beep virtual DevHlp service
#VDHEnumerateVDMs	Run worker function for each DOS session
#VDHGetCodePageFont	Return information of DOS session code page font
#VDHGetError	Get error code from last virtual DevHlp service
#VDHGetFlags	Get DOS Session's EFLAGS Register
#VDHHandleFromPID	Get handle for given Process ID
#VDHHandleFromSGID	Get DOS session handle from Screen Group ID
#VDHPopup	Display message
#VDHPutSysValue	Set system value
#VDHQueryLin	Get linear address for Far16 address
#VDHQuerySysValue	Query system value
#VDHRegisterAPI	Register API handler
#VDHReleaseCodePageFont	Release code page font
#VDHSetDosDevice	Register/install DOS device driver
#VDHSetError	Set error code
#VDHSetFlags	Set DOS session flags register

Parallel Port and Printer Services

Function	Type
#VDHPrintClose	Flush and close open printers for DOS session

Semaphore Services

Function	Type
#VDHCreateSem	Create event or mutex semaphore
#VDHDestroySem	Destroy semaphore
#VDHPostEventSem	Post event semaphore
#VDHQuerySem	Query semaphore state
#VDHReleaseMutexSem	Release mutex semaphore
#VDHRequestMutexSem	Request mutex semaphore
#VDHResetEventSem	Reset event semaphore
#VDHWaitEventSem	Wait on event semaphore

Note: These semaphore services above are used for synchronizing with an OS /2 process. Virtual device drivers must be careful not to block ( VDHRequestMutexSem/VDHWaitEventSem) in the context of a DOS session task; otherwise, that task will receive no more simulated hardware interrupts until it becomes unblocked.

Timer Services

Function	Type
#VDHArmTimerHook	Set timer service/handler
#VDHDisarmTimerHook	Cancel timer service

Virtual Interrupt Services

Function	Type
#VDHClearVIRR	Clear virtual IRR
#VDHCloseVIRQ	Deregister IRQ handler
#VDHOpenVIRQ	Register IRQ handler
#VDHQueryVIRQ	Query IRQ status on a DOS session
#VDHSendVEOI	Send virtual EOI to VPIC
#VDHSetVIRR	Set virtual interrupt request register (IRR)
#VDHWaitVIRRs	Wait until interrupt is simulated
#VDHWakeVIRRs	Wake up DOS session

V8086 Stack Manipulation Services

Function	Type
#VDHPopInt	Remove IRET frame from client DOS session stack
#VDHPopRegs	Pop client DOS session registers from client stack
#VDHPopStack	Pop data off client stack
#VDHPushFarCall	Simulate FAR call to V86 code
#VDHPushInt	Transfer control to V86 interrupt handler
#VDHPushRegs	Push client DOS session registers onto client stack
#VDHPushStack	Push 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 OptionFlag flag when the block
is created with VDHCreateBlockPool.
*/

include mvdm.inc

EXTERN  VDHAllocBlock:NEAR
SourceBlockPool  DD ?    ;  Handle to a memory block pool

PUSH    SourceBlockPool  ;  Push SourceBlockPool

CALL    VDHAllocBlock        ; Call the function

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

include mvdm.inc

EXTERN  VDHAllocBlock:NEAR
SourceBlockPool  DD ?    ;  Handle to a memory block pool

PUSH    SourceBlockPool  ;  Push SourceBlockPool

CALL    VDHAllocBlock        ; Call the function

VDHAllocBlock Parameter - SourceBlockPool

SourceBlockPool(DD) Handle to the pool of memory blocks from which to allocate a memory block.

VDHAllocBlock Return Value - rc

Success If the function is successful, it returns the address of the allocated memory block.

Failure If the function fails, it returns 0. 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(DD) Handle to the pool of memory blocks from which to allocate a memory block.

VDHAllocBlock - Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: Any blocks allocated by a virtual device driver for use by the terminating DOS session are freed by using VDHFreeBlock. Any block pools created for the DOS session should also be freed.

VDHAllocBlock - Topics

Select an item:

Format
Parameters 
Return Codes 
Purpose 
Glossary

VDHAllocDMABuffer

Select an item:

Format
Parameters 
Return Codes 
Purpose 
Glossary

/*

This   function   allocates   a   DMA   buffer . 
* / 

include   mvdm . inc 

EXTERN    VDHAllocDMABuffer : NEAR 
RequestSize     DD   ?      ;    Request   size 
Align64kFlag    DD   ?      ;    Alignment   flag 
PhysAddrPtr     DD   ?      ;    Location   to   store   the   physical   address   returned 

PUSH      RequestSize     ;    Push   RequestSize 
PUSH      Align64kFlag    ;    Push   Align64kFlag 
PUSH      PhysAddrPtr     ;    Push   PhysAddrPtr 

CALL      VDHAllocDMABuffer       ;   Call   the   function

VDHAllocDMABuffer - Format

/*

This   function   allocates   a   DMA   buffer . 
* / 

include   mvdm . inc 

EXTERN    VDHAllocDMABuffer : NEAR 
RequestSize     DD   ?      ;    Request   size 
Align64kFlag    DD   ?      ;    Alignment   flag 
PhysAddrPtr     DD   ?      ;    Location   to   store   the   physical   address   returned 

PUSH      RequestSize     ;    Push   RequestSize 
PUSH      Align64kFlag    ;    Push   Align64kFlag 
PUSH      PhysAddrPtr     ;    Push   PhysAddrPtr 

CALL      VDHAllocDMABuffer       ;   Call   the   function

VDHAllocDMABuffer Parameter - RequestSize

RequestSize(DD) 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(DD) Alignment flag.

If Align64kFlag=1, the buffer is at a 64KB alignment in physical memory. If Align64kFlag=0, the buffer is at a 128KB alignment in physical memory.

VDHAllocDMABuffer Parameter - PhysAddrPtr

PhysAddrPtr(DD) Location where VDHAllocDMABufferreturns the physical address of the allocation.

VDHAllocDMABuffer Return Value - rc

Success If the function is successful, it returns the linear address of allocation (system memory).

Failure If the function fails, it returns -1. VDHGetErrorshould be called to determine the nature of the problem.

VDHAllocDMABuffer - Parameters

RequestSize(DD) 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(DD) Alignment flag.

If Align64kFlag=1, the buffer is at a 64KB alignment in physical memory. If Align64kFlag=0, the buffer is at a 128KB alignment in physical memory.

PhysAddrPtr(DD) Location where VDHAllocDMABufferreturns the physical address of the allocation.

VDHAllocDMABuffer - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: The virtual device driver frees the buffer by using 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 . inc 

EXTERN    VDHAllocDOSMem : NEAR 
BlockSize    DD   ?      ;    Size   of   the   desired   memory   block   ( in   bytes ) 

PUSH      BlockSize    ;    Push   BlockSize 

CALL      VDHAllocDOSMem    ;   Call   the   function

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

EXTERN    VDHAllocDOSMem : NEAR 
BlockSize    DD   ?      ;    Size   of   the   desired   memory   block   ( in   bytes ) 

PUSH      BlockSize    ;    Push   BlockSize 

CALL      VDHAllocDOSMem    ;   Call   the   function

VDHAllocDOSMem Parameter - BlockSize

BlockSize(DD) Size of the desired memory block; the number of bytes to allocate.

VDHAllocDOSMem Return Value - rc

Success If the function is successful, it returns the address of the allocated memory block.

Failure If the function fails, it returns 0. 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(DD) Size of the desired memory block; the number of bytes to allocate.

VDHAllocDOSMem - Purpose

Context Issues: This function can be called only in the DOS session-task context (DOS session creation).

DOS Session Terminations: There are no DOS session termination implications for this function. The DOS Session Manager frees this memory.

Notes: There is no way to free memory taken from the DOS heap. If there is no free memory in the DOS memory area, the allocation fails. Allocations always start on paragraph (16-byte) boundaries.

VDHAllocDOSMem - Topics

Select an item:

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

EXTERN    VDHAllocHook : NEAR 
HookType       DD   ?      ;    Hook   type 
ArmHookFcn     DD   ?      ;    Arm   hook   function 
RefDataSize    DD   ?      ;    Size   of   the   reference   data 

PUSH      HookType       ;    Push   HookType 
PUSH      ArmHookFcn     ;    Push   ArmHookFcn 
PUSH      RefDataSize    ;    Push   RefDataSize 

CALL      VDHAllocHook      ;   Call   the   function

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

EXTERN    VDHAllocHook : NEAR 
HookType       DD   ?      ;    Hook   type 
ArmHookFcn     DD   ?      ;    Arm   hook   function 
RefDataSize    DD   ?      ;    Size   of   the   reference   data 

PUSH      HookType       ;    Push   HookType 
PUSH      ArmHookFcn     ;    Push   ArmHookFcn 
PUSH      RefDataSize    ;    Push   RefDataSize 

CALL      VDHAllocHook      ;   Call   the   function

VDHAllocHook Parameter - HookType

HookType(DD) 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(DD) Arm hook function.

VDHAllocHook Parameter - RefDataSize

RefDataSize(DD) Size of the reference data.

VDHAllocHook Return Value - rc

Success If the function is successful, it returns a hook handle, which is used in the Arm services.

Failure If there is an error, the function returns NULL. VDHGetErrorshould be called to determine the nature of the problem. If HookTypeor ArmHookFcnis invalid, a system halt occurs.

VDHAllocHook - Parameters

HookType(DD) 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(DD) Arm hook function.

RefDataSize(DD) Size of the reference data.

VDHAllocHook - Purpose

Context Issues: This function can be called in the initialization or DOS session-task context. However, VDH_RETURN_HOOK and VDH_BP_HOOK require the DOS session-task context.

DOS Session Terminations: During initialization time, hooks are allocated globally; that is, they are not associated with a DOS session process. These hooks are not automatically freed when a DOS session terminates. During DOS session creation time or thereafter, allocated hooks are associated with the current DOS session, and are freed when that DOS session terminates.

Notes: Use 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 . inc 

EXTERN    VDHAllocMem : NEAR 
NumBytes      DD   ? 
OptionFlag    DD   ?      ;    Number   of   bytes   to   allocate 

PUSH      NumBytes      ;    Push   NumBytes 
PUSH      OptionFlag    ;    Push   OptionFlag 

CALL      VDHAllocMem     ;   Call   the   function

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

EXTERN    VDHAllocMem : NEAR 
NumBytes      DD   ? 
OptionFlag    DD   ?      ;    Number   of   bytes   to   allocate 

PUSH      NumBytes      ;    Push   NumBytes 
PUSH      OptionFlag    ;    Push   OptionFlag 

CALL      VDHAllocMem     ;   Call   the   function

VDHAllocMem Parameter - NumBytes

NumBytes(DD) Number of bytes to allocate.

VDHAllocMem Parameter - OptionFlag

OptionFlag(DD) Bit flag describing the allocation options.

Possible value:

VDHAM_SWAPPABLE Allocate memory from the swappable heap. Otherwise, memory is allocated from the fixed heap and can be accessed at hardware interrupt time.

VDHAllocMem Return Value - rc

Success If the function is successful, it returns the address of the allocated space.

Failure If the function fails, it returns 0. VDHGetErrorshould be called to determine the nature of the problem. If either NumBytesor OptionFlagis invalid, a system halt occurs.

VDHAllocMem - Parameters

NumBytes(DD) Number of bytes to allocate.

OptionFlag(DD) Bit flag describing the allocation options.

Possible value:

VDHAM_SWAPPABLE Allocate memory from the swappable heap. Otherwise, memory is allocated from the fixed heap and can be accessed at hardware interrupt time.

VDHAllocMem - Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: All memory allocated by a virtual device driver for use by the terminating DOS session is freed by using VDHFreeMem.

Notes: Allocations larger than one page are performed by using VDHAllocPages. To access the allocated memory at hardware interrupt time, be sure to allocate memory from the fixed heap.

VDHAllocMem - Topics

Select an item:

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

EXTERN    VDHAllocPages : NEAR 
StartingAddress    DD   ?      ;    A   specific   linear   address 
NumPages           DD   ?      ;    The   number   of   pages   to   allocate 
OptionFlag         DD   ?      ;    Allocation   options   bit - flag 

PUSH      StartingAddress    ;    Push   StartingAddress 
PUSH      NumPages           ;    Push   NumPages 
PUSH      OptionFlag         ;    Push   OptionFlag 

CALL      VDHAllocPages          ;   Call   the   function

VDHAllocPages - Format

/*

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

include   mvdm . inc 

EXTERN    VDHAllocPages : NEAR 
StartingAddress    DD   ?      ;    A   specific   linear   address 
NumPages           DD   ?      ;    The   number   of   pages   to   allocate 
OptionFlag         DD   ?      ;    Allocation   options   bit - flag 

PUSH      StartingAddress    ;    Push   StartingAddress 
PUSH      NumPages           ;    Push   NumPages 
PUSH      OptionFlag         ;    Push   OptionFlag 

CALL      VDHAllocPages          ;   Call   the   function

VDHAllocPages Parameter - StartingAddress

StartingAddress(DD) A specific address used with the available options ( see Option Flag).

VDHAllocPages Parameter - NumPages

NumPages(DD) Number of pages of linear memory to allocate.

VDHAllocPages Parameter - OptionFlag

OptionFlag(DD) Bit flag indicating choices in allocation options.

This flag can take one or more of the following values:

VDHAP_SPECIFIC 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

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(DD) A specific address used with the available options ( see Option Flag).

NumPages(DD) Number of pages of linear memory to allocate.

OptionFlag(DD) Bit flag indicating choices in allocation options.

This flag can take one or more of the following values:

VDHAP_SPECIFIC 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 - 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 
VDHAllocHook   with   the   VDH _ BP _ HOOK   flag . 
* / 

include   mvdm . inc 

EXTERN    VDHArmBPHook : NEAR 
HookHandle    DD   ?      ;    Hook   handle 

PUSH      HookHandle    ;    Push   HookHandle 

CALL      VDHArmBPHook     ;   Call   the   function

VDHArmBPHook - Format

/*

This   function   obtains   the   address   of   the   V86   breakpoint   allocated   by 
a   previous   call   to 
VDHAllocHook   with   the   VDH _ BP _ HOOK   flag . 
* / 

include   mvdm . inc 

EXTERN    VDHArmBPHook : NEAR 
HookHandle    DD   ?      ;    Hook   handle 

PUSH      HookHandle    ;    Push   HookHandle 

CALL      VDHArmBPHook     ;   Call   the   function

VDHArmBPHook Parameter - HookHandle

HookHandle(DD) Hook handle allocated with VDHAllocHook.

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - p    - Pointer to hook-specific reference data
;           [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT   None
;
; CONTEXT   DOS session-task

VDHArmBPHook Return Value - rc

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

Failure If HookHandleis invalid, a system halt occurs.

VDHArmBPHook - Parameters

HookHandle(DD) Hook handle allocated with VDHAllocHook.

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - p    - Pointer to hook-specific reference data
;           [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT   None
;
; CONTEXT   DOS session-task

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

EXTERN    VDHArmContextHook : NEAR 
HookHandle    DD   ?      ;    Hook   handle   allocated   with   VDHAllocHook 
VDMHandle     DD   ?      ;    DOS   session   handle 

PUSH      HookHandle    ;    Push   HookHandle 
PUSH      VDMHandle     ;    Push   VDMHandle 

CALL      VDHArmContextHook     ;   Call   the   function

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

EXTERN    VDHArmContextHook : NEAR 
HookHandle    DD   ?      ;    Hook   handle   allocated   with   VDHAllocHook 
VDMHandle     DD   ?      ;    DOS   session   handle 

PUSH      HookHandle    ;    Push   HookHandle 
PUSH      VDMHandle     ;    Push   VDMHandle 

CALL      VDHArmContextHook     ;   Call   the   function

VDHArmContextHook Parameter - HookHandle

HookHandle(DD) Hook handle allocated with VDHAllocHook.

VDHArmContextHook Parameter - VDMHandle

VDMHandle(DD) DOS session handle. A value of -1 indicates a global context .

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;           [ESP + 4] - pcrf     - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   Task (global) or DOS session-task (local)
; NOTE      pcrf is valid only for local context hook handlers

VDHArmContextHook Return Value - rc

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(DD) Hook handle allocated with VDHAllocHook.

VDMHandle(DD) DOS session handle. A value of -1 indicates a global context .

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;           [ESP + 4] - pcrf     - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   Task (global) or DOS session-task (local)
; NOTE      pcrf is valid only for local context hook handlers

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   VDHPopInt   is   executed . 
* / 

include   mvdm . inc 

EXTERN    VDHArmReturnHook : NEAR 
HookHandle     DD   ?      ;    Hook   handle 
RetHookType    DD   ?      ;    Return   hook   type 

PUSH      HookHandle     ;    Push   HookHandle 
PUSH      RetHookType    ;    Push   RetHookType 

CALL      VDHArmReturnHook      ;   Call   the   function

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

include   mvdm . inc 

EXTERN    VDHArmReturnHook : NEAR 
HookHandle     DD   ?      ;    Hook   handle 
RetHookType    DD   ?      ;    Return   hook   type 

PUSH      HookHandle     ;    Push   HookHandle 
PUSH      RetHookType    ;    Push   RetHookType 

CALL      VDHArmReturnHook      ;   Call   the   function

VDHArmReturnHook Parameter - HookHandle

HookHandle(DD) Hook handles the routine to get control on an IRET/RETF. Allocated with VDHAllocHook.

VDHArmReturnHook Parameter - RetHookType

RetHookType(DD) Return hook type.

Possible values are:

VDHARH_NORMAL_IRET
VDHARH_NORMAL_RET
VDHARH_RECURSIVE_IRET
VDHARH_RECURSIVE_RET
VDHARH_CSEIP_HOOK
VDHARH_RECURSIVE_CSEIP_HOOK

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;           [ESP + 4] - pcrf     - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

VDHArmReturnHook Return Value - rc

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

Failure If VDHARH_NORMAL_x is already armed, the function returns 0. If HookHandleis invalid, a system halt occurs.

VDHArmReturnHook - Parameters

HookHandle(DD) Hook handles the routine to get control on an IRET/RETF. Allocated with VDHAllocHook.

RetHookType(DD) Return hook type.

Possible values are:

VDHARH_NORMAL_IRET
VDHARH_NORMAL_RET
VDHARH_RECURSIVE_IRET
VDHARH_RECURSIVE_RET
VDHARH_CSEIP_HOOK
VDHARH_RECURSIVE_CSEIP_HOOK

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;           [ESP + 4] - pcrf     - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

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

EXTERN    VDHArmSTIHook : NEAR 
HookHandle    DD   ?      ;    Hook   handle   allocated   with   VDHAllocHook 
VDMHandle     DD   ?      ;    DOS   session   handle 

PUSH      HookHandle    ;    Push   HookHandle 
PUSH      VDMHandle     ;    Push   VDMHandle 

CALL      VDHArmSTIHook     ;   Call   the   function

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

EXTERN    VDHArmSTIHook : NEAR 
HookHandle    DD   ?      ;    Hook   handle   allocated   with   VDHAllocHook 
VDMHandle     DD   ?      ;    DOS   session   handle 

PUSH      HookHandle    ;    Push   HookHandle 
PUSH      VDMHandle     ;    Push   VDMHandle 

CALL      VDHArmSTIHook     ;   Call   the   function

VDHArmSTIHook Parameter - HookHandle

HookHandle(DD) Hook handle allocated with VDHAllocHook.

VDHArmSTIHook Parameter - VDMHandle

VDMHandle(DD) DOS session handle.

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;           [ESP + 4] - pcrf     - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

VDHArmSTIHook Return Value - rc

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(DD) Hook handle allocated with VDHAllocHook.

VDMHandle(DD) DOS session handle.

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to reference data
;           [ESP + 4] - pcrf     - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

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

EXTERN    VDHArmTimerHook : NEAR 
HookHandle    DD   ?      ;    Timer   hook   handle 
Duration      DD   ?      ;    Duration   of   the   timeout   in   milliseconds 
VDMHandle     DD   ?      ;    DOS   session   handle 

PUSH      HookHandle    ;    Push   HookHandle 
PUSH      Duration      ;    Push   Duration 
PUSH      VDMHandle     ;    Push   VDMHandle 

CALL      VDHArmTimerHook     ;   Call   the   function

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

EXTERN    VDHArmTimerHook : NEAR 
HookHandle    DD   ?      ;    Timer   hook   handle 
Duration      DD   ?      ;    Duration   of   the   timeout   in   milliseconds 
VDMHandle     DD   ?      ;    DOS   session   handle 

PUSH      HookHandle    ;    Push   HookHandle 
PUSH      Duration      ;    Push   Duration 
PUSH      VDMHandle     ;    Push   VDMHandle 

CALL      VDHArmTimerHook     ;   Call   the   function

VDHArmTimerHook Parameter - HookHandle

HookHandle(DD) Timer hook handle.

VDHArmTimerHook Parameter - Duration

Duration(DD) Timer duration in milliseconds.

VDHArmTimerHook Parameter - VDMHandle

VDMHandle(DD) DOS session handle.

Possible values are:

DOS Session Handle or 0 When the specified time duration expires, a local context hook is automatically armed by using the specified HookHandle.

VDH_TIMER_GLOBAL_CONTEXT When the specified time duration expires, a global context hook is automatically armed by using the specified HookHandle.

VDH_TIMER_INTERRUPT_HOOK When the specified time duration expires, the timer hook specified by HookHandleis called at interrupt time.

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pRefData - Pointer to reference data
;    EXIT   None
;
; CONTEXT   Interrupt

VDHArmTimerHook Return Value - rc

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(DD) Timer hook handle.

Duration(DD) Timer duration in milliseconds.

VDMHandle(DD) DOS session handle.

Possible values are:

DOS Session Handle or 0 When the specified time duration expires, a local context hook is automatically armed by using the specified HookHandle.

VDH_TIMER_GLOBAL_CONTEXT When the specified time duration expires, a global context hook is automatically armed by using the specified HookHandle.

VDH_TIMER_INTERRUPT_HOOK When the specified time duration expires, the timer hook specified by HookHandleis called at interrupt time.

Hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pRefData - Pointer to reference data
;    EXIT   None
;
; CONTEXT   Interrupt

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   VDHAllocHook   with 
the   VDH _ BP _ HOOK   flag . 
* / 

include   mvdm . inc 

EXTERN    VDHArmVPMBPHook : NEAR 
HookHandle    DD   ?      ;    Hook   handle   allocated   with   VDHAllocHook 

PUSH      HookHandle    ;    Push   HookHandle 

CALL      VDHArmVPMBPHook     ;   Call   the   function

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

include   mvdm . inc 

EXTERN    VDHArmVPMBPHook : NEAR 
HookHandle    DD   ?      ;    Hook   handle   allocated   with   VDHAllocHook 

PUSH      HookHandle    ;    Push   HookHandle 

CALL      VDHArmVPMBPHook     ;   Call   the   function

VDHArmVPMBPHook Parameter - HookHandle

HookHandle(DD) Hook handle allocated with VDHAllocHook.

The hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to hook-specific reference data
;           [ESP + 4] - pcrf - Pointer to client register frame
;
;    EXIT   None
;
; CONTEXT   DOS session-task

VDHArmVPMBPHook Return Value - rc

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(DD) Hook handle allocated with VDHAllocHook.

The hook routine interface:

HookRoutine  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - pRefData - Pointer to hook-specific reference data
;           [ESP + 4] - pcrf - Pointer to client register frame
;
;    EXIT   None
;
; CONTEXT   DOS session-task

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

EXTERN    VDHBeginUseVPMStack : NEAR 
                DD   ? 

PUSH                      ;    Push 

CALL      VDHBeginUseVPMStack       ;   Call   the   function

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

EXTERN    VDHBeginUseVPMStack : NEAR 
                DD   ? 

PUSH                      ;    Push 

CALL      VDHBeginUseVPMStack       ;   Call   the   function

VDHBeginUseVPMStack Parameter -

(DD) None.

VDHBeginUseVPMStack Return Value -

None.

VDHBeginUseVPMStack - Parameters

(DD) None.

VDHBeginUseVPMStack - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: There must be a DPMI client running in the DOS session before calling this function.

VDHBeginUseVPMStack - Topics

Select an item:

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

EXTERN    VDHCallOutDMA : NEAR 
                DD   ? 

PUSH                      ;    Push 

CALL      VDHCallOutDMA       ;   Call   the   function

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

EXTERN    VDHCallOutDMA : NEAR 
                DD   ? 

PUSH                      ;    Push 

CALL      VDHCallOutDMA       ;   Call   the   function

VDHCallOutDMA Parameter -

(DD) None.

VDHCallOutDMA Return Value -

None.

VDHCallOutDMA - Parameters

(DD) None.

VDHCallOutDMA - Purpose

Context Issues: This function can be called in any context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHCallOutDMA - Topics

Select an item:

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

include   mvdm . inc 

EXTERN    VDHChangeVPMIF : NEAR 
SetIFFlag    DD   ?      ;    Indicates   whether   to   turn   the   IF   flag   on   or   off 

PUSH      SetIFFlag    ;    Push   SetIFFlag 

CALL      VDHChangeVPMIF    ;   Call   the   function

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

include   mvdm . inc 

EXTERN    VDHChangeVPMIF : NEAR 
SetIFFlag    DD   ?      ;    Indicates   whether   to   turn   the   IF   flag   on   or   off 

PUSH      SetIFFlag    ;    Push   SetIFFlag 

CALL      VDHChangeVPMIF    ;   Call   the   function

VDHChangeVPMIF Parameter - SetIFFlag

SetIFFlag(DD) Indicates whether to turn the IF flag ON or OFF. If nonzero, set IF flag to 1 (one). If zero, set IF flag to 0 (zero).

VDHChangeVPMIF Return Value - rc

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

Failure Not applicable to this function.

VDHChangeVPMIF - Parameters

SetIFFlag(DD) Indicates whether to turn the IF flag ON or OFF. If nonzero, set IF flag to 1 (one). If zero, set IF flag to 0 (zero).

VDHChangeVPMIF - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: The 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 . inc 

EXTERN    VDHCheckPagePerm : NEAR 
BasePage    DD   ?      ;    Base   virtual   page   number 
Reserved    DD   ?      ;    Reserved ;   must   be   set   to   zero 
NumPages    DD   ?      ;    Number   of   pages   to   verify 
Flag        DD   ?      ;    Flag 

PUSH      BasePage    ;    Push   BasePage 
PUSH      Reserved    ;    Push   Reserved 
PUSH      NumPages    ;    Push   NumPages 
PUSH      Flag        ;    Push   Flag 

CALL      VDHCheckPagePerm   ;   Call   the   function

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

EXTERN    VDHCheckPagePerm : NEAR 
BasePage    DD   ?      ;    Base   virtual   page   number 
Reserved    DD   ?      ;    Reserved ;   must   be   set   to   zero 
NumPages    DD   ?      ;    Number   of   pages   to   verify 
Flag        DD   ?      ;    Flag 

PUSH      BasePage    ;    Push   BasePage 
PUSH      Reserved    ;    Push   Reserved 
PUSH      NumPages    ;    Push   NumPages 
PUSH      Flag        ;    Push   Flag 

CALL      VDHCheckPagePerm   ;   Call   the   function

VDHCheckPagePerm Parameter - BasePage

BasePage(DD) Base virtual page number.

VDHCheckPagePerm Parameter - Reserved

Reserved(DD) Reserved. Must be set to 0.

VDHCheckPagePerm Parameter - NumPages

NumPages(DD) Number of pages to verify.

VDHCheckPagePerm Parameter - Flag

Flag(DD) Values are:

VPMPG_U Are the pages user-accessible?
VPMPG_W Are the pages writable?
VPMPG_R Are the pages readable (valid)?
VPMPG_X Are the pages executable?

VDHCheckPagePerm Return Value - rc

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

Failure If the function fails, it returns 0.

VDHCheckPagePerm - Parameters

BasePage(DD) Base virtual page number.

Reserved(DD) Reserved. Must be set to 0.

NumPages(DD) Number of pages to verify.

Flag(DD) Values are:

VPMPG_U Are the pages user-accessible?
VPMPG_W Are the pages writable?
VPMPG_R Are the pages readable (valid)?
VPMPG_X Are the pages executable?

VDHCheckPagePerm - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHCheckPagePerm - Topics

Select an item:

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

EXTERN    VDHCheckVPMIntVector : NEAR 
Vector    DD   ?      ;    Interrupt   vector   number 

PUSH      Vector    ;    Push   Vector 

CALL      VDHCheckVPMIntVecto ;   Call   the   function

VDHCheckVPMIntVector - Format

/*

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

include   mvdm . inc 

EXTERN    VDHCheckVPMIntVector : NEAR 
Vector    DD   ?      ;    Interrupt   vector   number 

PUSH      Vector    ;    Push   Vector 

CALL      VDHCheckVPMIntVecto ;   Call   the   function

VDHCheckVPMIntVector Parameter - Vector

Vector(DD) Interrupt vector number.

VDHCheckVPMIntVector Return Value - rc

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

Failure If there is no user-registered interrupt handler for the interrupt in Vector, the function returns 0 (zero).

VDHCheckVPMIntVector - Parameters

Vector(DD) Interrupt vector number.

VDHCheckVPMIntVector - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: There must be a DPMI client running in the DOS session before calling this function.

VDHCheckVPMIntVector - Topics

Select an item:

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

EXTERN    VDHClearVIRR : NEAR 
VDMHandle    DD   ?      ;    DOS   session   handle 
IRQHandle    DD   ?      ;    IRQ   handle   from   VDHOpenVIRQ 

PUSH      VDMHandle    ;    Push   VDMHandle 
PUSH      IRQHandle    ;    Push   IRQHandle 

CALL      VDHClearVIRR    ;   Call   the   function

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

EXTERN    VDHClearVIRR : NEAR 
VDMHandle    DD   ?      ;    DOS   session   handle 
IRQHandle    DD   ?      ;    IRQ   handle   from   VDHOpenVIRQ 

PUSH      VDMHandle    ;    Push   VDMHandle 
PUSH      IRQHandle    ;    Push   IRQHandle 

CALL      VDHClearVIRR    ;   Call   the   function

VDHClearVIRR Parameter - VDMHandle

VDMHandle(DD) DOS session handle. A value of 0 (zero) indicates the current DOS session.

VDHClearVIRR Parameter - IRQHandle

IRQHandle(DD) IRQ handle from VDHOpenVIRQ.

VDHClearVIRR Return Value - rc

Success If the function was successful, it returns nothing.

Failure If either of the parameters is invalid, a system halt occurs.

VDHClearVIRR - Parameters

VDMHandle(DD) DOS session handle. A value of 0 (zero) indicates the current DOS session.

IRQHandle(DD) IRQ handle from VDHOpenVIRQ.

VDHClearVIRR - Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHClearVIRR - Topics

Select an item:

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

EXTERN    VDHClose : NEAR 
FileHandle    DW   ?      ;    Handle   to   the   file   or   device   to   close 

PUSH      FileHandle    ;    Push   FileHandle 

CALL      VDHClose     ;   Call   the   function

VDHClose - Format

/*

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

include   mvdm . inc 

EXTERN    VDHClose : NEAR 
FileHandle    DW   ?      ;    Handle   to   the   file   or   device   to   close 

PUSH      FileHandle    ;    Push   FileHandle 

CALL      VDHClose     ;   Call   the   function

VDHClose Parameter - FileHandle

FileHandle(DW) Handle (from VDHOpen) to the file or device to close.

VDHClose Return Value - rc

Success If the function is successful, it returns nothing.

Failure If FileHandleis invalid or if the DOS session is not in the DOS session-task context, a system halt occurs.

VDHClose - Parameters

FileHandle(DW) Handle (from VDHOpen) to the file or device to close.

VDHClose - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: Any handles opened by the virtual device driver for the terminating DOS session must be closed.

VDHClose - Topics

Select an item:

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

EXTERN    VDHCloseVDD : NEAR 
VDDHandle    DD   ?      ;    Handle   to   the   file   or   device   to   close 

PUSH      VDDHandle    ;    Push   VDDHandle 

CALL      VDHCloseVDD    ;   Call   the   function

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

EXTERN    VDHCloseVDD : NEAR 
VDDHandle    DD   ?      ;    Handle   to   the   file   or   device   to   close 

PUSH      VDDHandle    ;    Push   VDDHandle 

CALL      VDHCloseVDD    ;   Call   the   function

VDHCloseVDD Parameter - VDDHandle

VDDHandle(DD) Handle (from VDHOpenVDD) to the virtual device driver to close.

VDHCloseVDD Return Value - rc

Success If the function is successful, it returns nothing.

Failure If VDMHandleis invalid, a system halt occurs.

VDHCloseVDD - Parameters

VDDHandle(DD) Handle (from VDHOpenVDD) to the virtual device driver to close.

VDHCloseVDD - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: If a virtual device driver has a VDD/VDD session for a particular DOS session, that session is closed when the DOS session terminates.

Notes: This service is used to close the type of VDD/VDD connections, which are temporary or are on a per-DOS session basis.

VDHCloseVDD - Topics

Select an item:

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

EXTERN    VDHCloseVIRQ : NEAR 
IRQHandl    DD   ?      ;    Handle   of   the   virtual   device   driver   to   close 

PUSH      IRQHandl    ;    Push   IRQHandl 

CALL      VDHCloseVIRQ   ;   Call   the   function

VDHCloseVIRQ - Format

/*

This   function   closes   the   virtual   IRQ   handle   passed   to   it . 
* / 

include   mvdm . inc 

EXTERN    VDHCloseVIRQ : NEAR 
IRQHandl    DD   ?      ;    Handle   of   the   virtual   device   driver   to   close 

PUSH      IRQHandl    ;    Push   IRQHandl 

CALL      VDHCloseVIRQ   ;   Call   the   function

VDHCloseVIRQ Parameter - IRQHandl

IRQHandl(DD) Handle to the IRQ (from VDHOpenVIRQ) to close.

VDHCloseVIRQ Return Value - rc

Success If the function was successful, it returns nothing.

Failure If IRQHandleis invalid, a system halt occurs.

VDHCloseVIRQ - Parameters

IRQHandl(DD) Handle to the IRQ (from VDHOpenVIRQ) to close.

VDHCloseVIRQ - Purpose

Context Issues: This function can be called only in the initialization context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHCloseVIRQ - Topics

Select an item:

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

EXTERN    VDHCopyMem : NEAR 
Source         DD   ?      ;    Address   of   the   data   to   copy 
Destination    DD   ?      ;    Address   to   copy   the   data   to 
NumBytes       DD   ?      ;    Number   of   bytes   to   copy 

PUSH      Source         ;    Push   Source 
PUSH      Destination    ;    Push   Destination 
PUSH      NumBytes       ;    Push   NumBytes 

CALL      VDHCopyMem      ;   Call   the   function

VDHCopyMem - Format

/*

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

include   mvdm . inc 

EXTERN    VDHCopyMem : NEAR 
Source         DD   ?      ;    Address   of   the   data   to   copy 
Destination    DD   ?      ;    Address   to   copy   the   data   to 
NumBytes       DD   ?      ;    Number   of   bytes   to   copy 

PUSH      Source         ;    Push   Source 
PUSH      Destination    ;    Push   Destination 
PUSH      NumBytes       ;    Push   NumBytes 

CALL      VDHCopyMem      ;   Call   the   function

VDHCopyMem Parameter - Source

Source(DD) Address of the source data to be copied.

VDHCopyMem Parameter - Destination

Destination(DD) Address to which the data is to be copied.

VDHCopyMem Parameter - NumBytes

NumBytes(DD) Number of bytes to copy.

VDHCopyMem Return Value - rc

Success If the function is successful, it returns nothing.

Failure If NumBytesis 0 (zero), a system halt occurs.

VDHCopyMem - Parameters

Source(DD) Address of the source data to be copied.

Destination(DD) Address to which the data is to be copied.

NumBytes(DD) Number of bytes to copy.

VDHCopyMem - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Protection faults are handled as if a user application had performed the access. Therefore, writing to an invalid page causes a virtual device driver page fault handler to gain control. If there is no virtual device driver fault handler, a "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 . inc 

EXTERN    VDHCreateBlockPool : NEAR 
BlockSize     DD   ?      ;    Size   of   block   to   initialize   ( in   bytes ) 
OptionFlag    DD   ?      ;    Allocation   options   bit   flag 

PUSH      BlockSize     ;    Push   BlockSize 
PUSH      OptionFlag    ;    Push   OptionFlag 

CALL      VDHCreateBlockPool     ;   Call   the   function

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

EXTERN    VDHCreateBlockPool : NEAR 
BlockSize     DD   ?      ;    Size   of   block   to   initialize   ( in   bytes ) 
OptionFlag    DD   ?      ;    Allocation   options   bit   flag 

PUSH      BlockSize     ;    Push   BlockSize 
PUSH      OptionFlag    ;    Push   OptionFlag 

CALL      VDHCreateBlockPool     ;   Call   the   function

VDHCreateBlockPool Parameter - BlockSize

BlockSize(DD) Size of block to initialize (in bytes).

VDHCreateBlockPool Parameter - OptionFlag

OptionFlag(DD) Allocation options bit flag. Possible value:

VDHCBP_SWAPPABLE Blocks are allocated from the swappable heap. Otherwise, blocks are allocated from the fixed heap and can be accessed at hardware interrupt time.

VDHCreateBlockPool Return Value - rc

Success If the function is successful, it returns a handle to the pool of memory blocks.

Failure If the function fails, it returns 0 (zero). 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(DD) Size of block to initialize (in bytes).

OptionFlag(DD) Allocation options bit flag. Possible value:

VDHCBP_SWAPPABLE Blocks are allocated from the swappable heap. Otherwise, blocks are allocated from the fixed heap and can be accessed at hardware interrupt time.

VDHCreateBlockPool - Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: Any block pools allocated by a virtual device driver for use by the terminating DOS session is freed by using VDHDestroyBlockPool.

VDHCreateBlockPool - Topics

Select an item:

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

EXTERN    VDHCreateSel : NEAR 
LinearAddress    DD   ?      ;    Linear   address   of   the   start   of   the   buffer 
BufferSize       DD   ?      ;    Size   of   the   buffer   in   bytes 

PUSH      LinearAddress    ;    Push   LinearAddress 
PUSH      BufferSize       ;    Push   BufferSize 

CALL      VDHCreateSel        ;   Call   the   function

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

EXTERN    VDHCreateSel : NEAR 
LinearAddress    DD   ?      ;    Linear   address   of   the   start   of   the   buffer 
BufferSize       DD   ?      ;    Size   of   the   buffer   in   bytes 

PUSH      LinearAddress    ;    Push   LinearAddress 
PUSH      BufferSize       ;    Push   BufferSize 

CALL      VDHCreateSel        ;   Call   the   function

VDHCreateSel Parameter - LinearAddress

LinearAddress(DD) Linear address of the beginning of the buffer.

VDHCreateSel Parameter - BufferSize

BufferSize(DD) Size of the buffer in bytes. The expected range is 0-65535 with 0 interpreted as 65536.

VDHCreateSel Return Value - rc

Success If the function is successful, it returns a nonzero selector value such that SELECTOR:0 points to the first byte of the linear range.

Failure If BufferSizeis greater than 65535 or if there are no more selectors available, a system halt occurs.

VDHCreateSel - Parameters

LinearAddress(DD) Linear address of the beginning of the buffer.

BufferSize(DD) Size of the buffer in bytes. The expected range is 0-65535 with 0 interpreted as 65536.

VDHCreateSel - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: Any selectors created to map memory in the terminating DOS session must be destroyed with VDHDestroySel. The virtual device driver must ensure that any physical device driver that was given these selectors is finished with them.

Notes: The linear address must be in system memory. To create a 16:16 pointer to a DOS session address (in the 0 to 1MB+64KB range), use the HVDM (DOS session handle) alias linear address. 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 . inc 

EXTERN    VDHCreateSem : NEAR 
SemHandlePointer    DD   ?      ;    Semaphore   handle   address 
SemType              DD   ?      ;    Type   of   semaphore   of   create 

PUSH      SemHandlePointer    ;    Push   SemHandlePointer 
PUSH      SemType              ;    Push   SemType 

CALL      VDHCreateSem           ;   Call   the   function

VDHCreateSem - Format

/*

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

include   mvdm . inc 

EXTERN    VDHCreateSem : NEAR 
SemHandlePointer    DD   ?      ;    Semaphore   handle   address 
SemType              DD   ?      ;    Type   of   semaphore   of   create 

PUSH      SemHandlePointer    ;    Push   SemHandlePointer 
PUSH      SemType              ;    Push   SemType 

CALL      VDHCreateSem           ;   Call   the   function

VDHCreateSem Parameter - SemHandlePointer

SemHandlePointer(DD) Semaphore handle address.

VDHCreateSem Parameter - SemType

SemType(DD) Type of semaphore to create.

Values are:

VDH_EVENTSEM Event semaphore
VDH_MUTEXSEM Mutex semaphore

VDHCreateSem Return Value - rc

Success If the function is successful, it returns a nonzero value and places a handle to the semaphore in SemHandlePointer.

Failure If the function fails, it returns 0. VDHGetErrorshould be called to determine the nature of the problem. An invalid semaphore type causes a system halt to occur.

VDHCreateSem - Parameters

SemHandlePointer(DD) Semaphore handle address.

SemType(DD) Type of semaphore to create.

Values are:

VDH_EVENTSEM Event semaphore
VDH_MUTEXSEM Mutex semaphore

VDHCreateSem - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: These semaphores are global and are not attached to a specific DOS session. If a virtual device driver maintains semaphores on a per-DOS session basis, it destroys the semaphores by using 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.inc

EXTERN  VDHDecodeProperty:NEAR
ppProperty      DD ?    ;  Pointer to a pointer to property string
StartNumberPtr  DD ?    ;  Location to return the starting number
EndNumberPtr    DD ?    ;  Location to return the ending number
BaseFlag        DD ?    ;  Flag indicating the numeric base to use

PUSH    ppProperty      ;  Push ppProperty
PUSH    StartNumberPtr  ;  Push StartNumberPtr
PUSH    EndNumberPtr    ;  Push EndNumberPtr
PUSH    BaseFlag        ;  Push BaseFlag

CALL    VDHDecodeProperty       ; Call the function

VDHDecodeProperty - Format

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

include mvdm.inc

EXTERN  VDHDecodeProperty:NEAR
ppProperty      DD ?    ;  Pointer to a pointer to property string
StartNumberPtr  DD ?    ;  Location to return the starting number
EndNumberPtr    DD ?    ;  Location to return the ending number
BaseFlag        DD ?    ;  Flag indicating the numeric base to use

PUSH    ppProperty      ;  Push ppProperty
PUSH    StartNumberPtr  ;  Push StartNumberPtr
PUSH    EndNumberPtr    ;  Push EndNumberPtr
PUSH    BaseFlag        ;  Push BaseFlag

CALL    VDHDecodeProperty       ; Call the function

VDHDecodeProperty Parameter - ppProperty

ppProperty(DD) A pointer to a pointer to the property string to be decoded .

VDHDecodeProperty Parameter - StartNumberPtr

StartNumberPtr(DD) Location for storing the returned starting number.

VDHDecodeProperty Parameter - EndNumberPtr

EndNumberPtr(DD) Location for storing the returned ending number.

VDHDecodeProperty Parameter - BaseFlag

BaseFlag(DD) Flag indicating which numeric base to use:

VDH_DP_DECIMAL Decimal
VDH_DP_HEX Hex

VDHDecodeProperty Return Value - rc

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(DD) A pointer to a pointer to the property string to be decoded .

StartNumberPtr(DD) Location for storing the returned starting number.

EndNumberPtr(DD) Location for storing the returned ending number.

BaseFlag(DD) Flag indicating which numeric base to use:

VDH_DP_DECIMAL Decimal
VDH_DP_HEX Hex

VDHDecodeProperty - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: If a single value is found, 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 . inc 

EXTERN    VDHDestroyBlockPool : NEAR 
PoolHandle    DD   ?      ;    Handle   to   the   memory   block   pool   to   release 

PUSH      PoolHandle    ;    Push   PoolHandle 

CALL      VDHDestroyBlockPool     ;   Call   the   function

VDHDestroyBlockPool - Format

/*

This   function   releases   a   memory   block   pool . 
* / 

include   mvdm . inc 

EXTERN    VDHDestroyBlockPool : NEAR 
PoolHandle    DD   ?      ;    Handle   to   the   memory   block   pool   to   release 

PUSH      PoolHandle    ;    Push   PoolHandle 

CALL      VDHDestroyBlockPool     ;   Call   the   function

VDHDestroyBlockPool Parameter - PoolHandle

PoolHandle(DD) Handle to the memory block pool to release.

VDHDestroyBlockPool Return Value - rc

Success If the function was successful, it returns nothing.

Failure An invalid memory block pool handle causes a system halt to occur.

VDHDestroyBlockPool - Parameters

PoolHandle(DD) Handle to the memory block pool to release.

VDHDestroyBlockPool - Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHDestroyBlockPool - Topics

Select an item:

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

EXTERN    VDHDestroySel : NEAR 
GDTSelector    DW   ?      ;    GDT   selector   to   destroy 

PUSH      GDTSelector    ;    Push   GDTSelector 

CALL      VDHDestroySel      ;   Call   the   function

VDHDestroySel - Format

/*

This   function   destroys 
a   GDT   selector   created   by   VDHCreateSel . 
* / 

include   mvdm . inc 

EXTERN    VDHDestroySel : NEAR 
GDTSelector    DW   ?      ;    GDT   selector   to   destroy 

PUSH      GDTSelector    ;    Push   GDTSelector 

CALL      VDHDestroySel      ;   Call   the   function

VDHDestroySel Parameter - GDTSelector

GDTSelector(DW) GDT selector to be destroyed.

VDHDestroySel Return Value - rc

Success If the function is successful, it returns nothing.

Failure If GDTSelectorwas not created by VDHCreateSel, a system halt occurs.

VDHDestroySel - Parameters

GDTSelector(DW) GDT selector to be destroyed.

VDHDestroySel - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: All selectors created with 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 . inc 

EXTERN    VDHDestroySem : NEAR 
SemHandle    DD   ?      ;    Semaphore   handle   to   destroy 

PUSH      SemHandle    ;    Push   SemHandle 

CALL      VDHDestroySem    ;   Call   the   function

VDHDestroySem - Format

/*

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

include   mvdm . inc 

EXTERN    VDHDestroySem : NEAR 
SemHandle    DD   ?      ;    Semaphore   handle   to   destroy 

PUSH      SemHandle    ;    Push   SemHandle 

CALL      VDHDestroySem    ;   Call   the   function

VDHDestroySem Parameter - SemHandle

SemHandle(DD) Handle of the semaphore to destroy.

VDHDestroySem Return Value - rc

Success If the function is successful, it returns nothing.

Failure If SemHandleis invalid or if the semaphore is reset or owned, a system halt occurs.

VDHDestroySem - Parameters

SemHandle(DD) Handle of the semaphore to destroy.

VDHDestroySem - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHDestroySem - Topics

Select an item:

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

EXTERN    VDHDevBeep : NEAR 
Frequency    DD   ?      ;    Frequency   of   the   beep   in   hertz 
Duration     DD   ?      ;    Duration   of   the   beep   in   milliseconds 

PUSH      Frequency    ;    Push   Frequency 
PUSH      Duration     ;    Push   Duration 

CALL      VDHDevBeep    ;   Call   the   function

VDHDevBeep - Format

/*

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

include   mvdm . inc 

EXTERN    VDHDevBeep : NEAR 
Frequency    DD   ?      ;    Frequency   of   the   beep   in   hertz 
Duration     DD   ?      ;    Duration   of   the   beep   in   milliseconds 

PUSH      Frequency    ;    Push   Frequency 
PUSH      Duration     ;    Push   Duration 

CALL      VDHDevBeep    ;   Call   the   function

VDHDevBeep Parameter - Frequency

Frequency(DD) Frequency of the beep in hertz.

VDHDevBeep Parameter - Duration

Duration(DD) Duration of the beep in milliseconds.

VDHDevBeep Return Value - rc

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

Failure If the function fails, it returns 0.

VDHDevBeep - Parameters

Frequency(DD) Frequency of the beep in hertz.

Duration(DD) Duration of the beep in milliseconds.

VDHDevBeep - Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHDevBeep - Topics

Select an item:

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   DosDevIOCtl   API . 
Refer   to   the 
OS / 2   Control   Program   Programming   Reference 
for   a   complete 
description   of   each   DosDevIOCtl   API   parameter . 
* / 

include   mvdm . inc 

EXTERN    VDHDevIOCtl : NEAR 
DevHandle          DW   ?      ;    Device   handle   returned   by   VDHOpen   or   VDHPhysicalDisk 
Category           DD   ?      ;    Category   of   function   performed 
Function           DD   ?      ;    Function   within   category   performed 
ParmList           DD   ?      ;    Pointer   to   command - specific   input   parameter   area 
ParmLengthMax      DD   ?      ;    Maximum   size   of   input   parameter   area ,   in   bytes 
ParmLengthInOut    DD   ?      ;    Pointer   to   length   of   the   parameters   passed ,   in   bytes 
DataArea           DD   ?      ;    Pointer   to   the   data   area 
DataLengthMax      DD   ?      ;    Maximum   size   of   the   parameters   passed ,   in   bytes 
DataLengthInOut    DD   ?      ;    Pointer   to   length   of   the   parameters   passed ,   in   bytes 

PUSH      DevHandle          ;    Push   DevHandle 
PUSH      Category           ;    Push   Category 
PUSH      Function           ;    Push   Function 
PUSH      ParmList           ;    Push   ParmList 
PUSH      ParmLengthMax      ;    Push   ParmLengthMax 
PUSH      ParmLengthInOut    ;    Push   ParmLengthInOut 
PUSH      DataArea           ;    Push   DataArea 
PUSH      DataLengthMax      ;    Push   DataLengthMax 
PUSH      DataLengthInOut    ;    Push   DataLengthInOut 

CALL      VDHDevIOCtl          ;   Call   the   function

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

include   mvdm . inc 

EXTERN    VDHDevIOCtl : NEAR 
DevHandle          DW   ?      ;    Device   handle   returned   by   VDHOpen   or   VDHPhysicalDisk 
Category           DD   ?      ;    Category   of   function   performed 
Function           DD   ?      ;    Function   within   category   performed 
ParmList           DD   ?      ;    Pointer   to   command - specific   input   parameter   area 
ParmLengthMax      DD   ?      ;    Maximum   size   of   input   parameter   area ,   in   bytes 
ParmLengthInOut    DD   ?      ;    Pointer   to   length   of   the   parameters   passed ,   in   bytes 
DataArea           DD   ?      ;    Pointer   to   the   data   area 
DataLengthMax      DD   ?      ;    Maximum   size   of   the   parameters   passed ,   in   bytes 
DataLengthInOut    DD   ?      ;    Pointer   to   length   of   the   parameters   passed ,   in   bytes 

PUSH      DevHandle          ;    Push   DevHandle 
PUSH      Category           ;    Push   Category 
PUSH      Function           ;    Push   Function 
PUSH      ParmList           ;    Push   ParmList 
PUSH      ParmLengthMax      ;    Push   ParmLengthMax 
PUSH      ParmLengthInOut    ;    Push   ParmLengthInOut 
PUSH      DataArea           ;    Push   DataArea 
PUSH      DataLengthMax      ;    Push   DataLengthMax 
PUSH      DataLengthInOut    ;    Push   DataLengthInOut 

CALL      VDHDevIOCtl          ;   Call   the   function

VDHDevIOCtl Parameter - DevHandle

DevHandle(DW) Device handle returned by VDHOpenor VDHPhysicalDisk.

VDHDevIOCtl Parameter - Category

Category(DD) Category of function performed.

VDHDevIOCtl Parameter - Function

Function(DD) Function within category performed.

VDHDevIOCtl Parameter - ParmList

ParmList(DD) Pointer to the command-specific input parameter area.

VDHDevIOCtl Parameter - ParmLengthMax

ParmLengthMax(DD) Maximum size of the application input parameter area, in bytes. ParmLengthInOutcan be longer than this on input, but not on output.

VDHDevIOCtl Parameter - ParmLengthInOut

ParmLengthInOut(DD) Pointer to the length (in bytes) of the parameters passed by the caller in ParmList.

VDHDevIOCtl Parameter - DataArea

DataArea(DD) Pointer to the data area.

VDHDevIOCtl Parameter - DataLengthMax

DataLengthMax(DD) Maximum size of the application data area, in bytes.

VDHDevIOCtl Parameter - DataLengthInOut

DataLengthInOut(DD) Pointer to the length (in bytes) of the parameters passed by the caller in ParmList. ParmLengthInOutcan be longer than this on input, but not on output.

VDHDevIOCtl Return Value - rc

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

Failure If the function fails, it returns 0. 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(DW) Device handle returned by VDHOpenor VDHPhysicalDisk.

Category(DD) Category of function performed.

Function(DD) Function within category performed.

ParmList(DD) Pointer to the command-specific input parameter area.

ParmLengthMax(DD) Maximum size of the application input parameter area, in bytes. ParmLengthInOutcan be longer than this on input, but not on output.

ParmLengthInOut(DD) Pointer to the length (in bytes) of the parameters passed by the caller in ParmList.

DataArea(DD) Pointer to the data area.

DataLengthMax(DD) Maximum size of the application data area, in bytes.

DataLengthInOut(DD) Pointer to the length (in bytes) of the parameters passed by the caller in ParmList. ParmLengthInOutcan be longer than this on input, but not on output.

VDHDevIOCtl - Purpose

Context Issues: This function can be called only in the DOS session task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Addresses (pointers) inside device-specific Data or Parameter Packets are not translated.

VDHDevIOCtl - Topics

Select an item:

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   VDHArmTimerHook 
before   the   handler   was   called . 
* / 

include   mvdm . inc 

EXTERN    VDHDisarmTimerHook : NEAR 
TimerHook    DD   ?      ;    Handle   to   the   timer   hook   to   disarm 

PUSH      TimerHook    ;    Push   TimerHook 

CALL      VDHDisarmTimerHook    ;   Call   the   function

VDHDisarmTimerHook - Format

/*

This   function   cancels 
a   timer   that   was   installed   by   VDHArmTimerHook 
before   the   handler   was   called . 
* / 

include   mvdm . inc 

EXTERN    VDHDisarmTimerHook : NEAR 
TimerHook    DD   ?      ;    Handle   to   the   timer   hook   to   disarm 

PUSH      TimerHook    ;    Push   TimerHook 

CALL      VDHDisarmTimerHook    ;   Call   the   function

VDHDisarmTimerHook Parameter - TimerHook

TimerHook(DD) Handle to the timer hook to disarm.

VDHDisarmTimerHook Return Value - rc

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

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould be called to determine the nature of the problem. If TimerHookis invalid, a system halt occurs.

VDHDisarmTimerHook - Parameters

TimerHook(DD) Handle to the timer hook to disarm.

VDHDisarmTimerHook - Purpose

Context Issues: This function can be called in the initialization, task, or interrupt context.

DOS Session Terminations: Any timer hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager at DOS session termination.

VDHDisarmTimerHook - Topics

Select an item:

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

EXTERN    VDHEndUseVPMStack : NEAR 
                DD   ? 

PUSH                      ;    Push 

CALL      VDHEndUseVPMStack       ;   Call   the   function

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

EXTERN    VDHEndUseVPMStack : NEAR 
                DD   ? 

PUSH                      ;    Push 

CALL      VDHEndUseVPMStack       ;   Call   the   function

VDHEndUseVPMStack Parameter -

(DD) None.

VDHEndUseVPMStack Return Value -

None.

VDHEndUseVPMStack - Parameters

(DD) None.

VDHEndUseVPMStack - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: There must be a DPMI client running in the DOS session before calling this function.

VDHEndUseVPMStack - Topics

Select an item:

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

EXTERN    VDHEnumerateVDMs : NEAR 
WorkerFcn    DD   ?      ;    Worker   function 
FcnData      DD   ?      ;    Function - specific   data   to   be   passed   each   call 

PUSH      WorkerFcn    ;    Push   WorkerFcn 
PUSH      FcnData      ;    Push   FcnData 

CALL      VDHEnumerateVDMs    ;   Call   the   function

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

EXTERN    VDHEnumerateVDMs : NEAR 
WorkerFcn    DD   ?      ;    Worker   function 
FcnData      DD   ?      ;    Function - specific   data   to   be   passed   each   call 

PUSH      WorkerFcn    ;    Push   WorkerFcn 
PUSH      FcnData      ;    Push   FcnData 

CALL      VDHEnumerateVDMs    ;   Call   the   function

VDHEnumerateVDMs Parameter - WorkerFcn

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

The worker function uses the following interface:

EnumHook  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hVDM   - Handle to DOS session
;           [ESP + 4] - ulData - Function-specific data
;    EXIT   SUCCESS - Return a non-zero value in EAX, enumeration continues
;           FAILURE - Return 0 in EAX, stop enumeration

VDHEnumerateVDMs Parameter - FcnData

FcnData(DD) Function-specific data to be passed each call.

VDHEnumerateVDMs Return Value - rc

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

Failure If the function fails, it returns 0 indicating that a worker function stopped the enumeration.

VDHEnumerateVDMs - Parameters

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

The worker function uses the following interface:

EnumHook  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hVDM   - Handle to DOS session
;           [ESP + 4] - ulData - Function-specific data
;    EXIT   SUCCESS - Return a non-zero value in EAX, enumeration continues
;           FAILURE - Return 0 in EAX, stop enumeration

FcnData(DD) Function-specific data to be passed each call.

VDHEnumerateVDMs - Purpose

Context Issues: This function can be called in the task and interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHEnumerateVDMs - Topics

Select an item:

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

EXTERN    VDHExchangeMem : NEAR 
Source         DD   ?      ;    Source   data   address 
Destination    DD   ?      ;    Destination   address 
NumBytes       DD   ?      ;    Number   of   bytes   to   be   exchanged 

PUSH      Source         ;    Push   Source 
PUSH      Destination    ;    Push   Destination 
PUSH      NumBytes       ;    Push   NumBytes 

CALL      VDHExchangeMem      ;   Call   the   function

VDHExchangeMem - Format

/*

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

include   mvdm . inc 

EXTERN    VDHExchangeMem : NEAR 
Source         DD   ?      ;    Source   data   address 
Destination    DD   ?      ;    Destination   address 
NumBytes       DD   ?      ;    Number   of   bytes   to   be   exchanged 

PUSH      Source         ;    Push   Source 
PUSH      Destination    ;    Push   Destination 
PUSH      NumBytes       ;    Push   NumBytes 

CALL      VDHExchangeMem      ;   Call   the   function

VDHExchangeMem Parameter - Source

Source(DD) Address of the source data.

VDHExchangeMem Parameter - Destination

Destination(DD) Address of the target region.

VDHExchangeMem Parameter - NumBytes

NumBytes(DD) Number of bytes to exchange.

VDHExchangeMem Return Value - rc

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

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould be called to determine the nature of the problem.

VDHExchangeMem - Parameters

Source(DD) Address of the source data.

Destination(DD) Address of the target region.

NumBytes(DD) Number of bytes to exchange.

VDHExchangeMem - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This function fails if the two memory regions to be exchanged overlap. Protection faults are handled as if a user application had performed the access. Therefore, writing to read-only pages or invalid page -table entries causes a virtual device driver page fault handler to gain control or causes the default behavior (that is, DOS session termination). This function also yields the CPU, if it is necessary to ensure that the thread dispatch latency limit is not exceeded.

VDHExchangeMem - Topics

Select an item:

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

EXTERN    VDHFindFreePages : NEAR 
StartAddress    DD   ?      ;    Starting   address 
Pages           DD   ?      ;    Size   of   the   range   ( in   pages ) 

PUSH      StartAddress    ;    Push   StartAddress 
PUSH      Pages           ;    Push   Pages 

CALL      VDHFindFreePages       ;   Call   the   function

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

EXTERN    VDHFindFreePages : NEAR 
StartAddress    DD   ?      ;    Starting   address 
Pages           DD   ?      ;    Size   of   the   range   ( in   pages ) 

PUSH      StartAddress    ;    Push   StartAddress 
PUSH      Pages           ;    Push   Pages 

CALL      VDHFindFreePages       ;   Call   the   function

VDHFindFreePages Parameter - StartAddress

StartAddress(DD) Starting address of the linear memory range to be searched. Must be page-aligned and between 0 and 110000H (1MB+64KB).

VDHFindFreePages Parameter - Pages

Pages(DD) On input: The size of the linear memory range to search, in pages.

On output: The size of the region found, in pages.

VDHFindFreePages Return Value - rc

Success If the function is successful, it returns the address of the region found and sets 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(DD) Starting address of the linear memory range to be searched. Must be page-aligned and between 0 and 110000H (1MB+64KB).

Pages(DD) On input: The size of the linear memory range to search, in pages.

On output: The size of the region found, in pages.

VDHFindFreePages - Purpose

Context Issues: This function can be called in the initialization context where it searches only the global linear map. This function can also be called in DOS session-task context (DOS session creation only), where it searches only the DOS session's private linear map.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHFindFreePages - Topics

Select an item:

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

EXTERN    VDHFreeBlock : NEAR 
PoolHandle     DD   ?      ;    Handle   to   a   memory   block   pool 
BlockToFree    DD   ?      ;    Address   of   the   memory   block   to   free 

PUSH      PoolHandle     ;    Push   PoolHandle 
PUSH      BlockToFree    ;    Push   BlockToFree 

CALL      VDHFreeBlock      ;   Call   the   function

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

EXTERN    VDHFreeBlock : NEAR 
PoolHandle     DD   ?      ;    Handle   to   a   memory   block   pool 
BlockToFree    DD   ?      ;    Address   of   the   memory   block   to   free 

PUSH      PoolHandle     ;    Push   PoolHandle 
PUSH      BlockToFree    ;    Push   BlockToFree 

CALL      VDHFreeBlock      ;   Call   the   function

VDHFreeBlock Parameter - PoolHandle

PoolHandle(DD) Handle (from VDHCreateBlockPool) to the pool of memory blocks that contains the memory block to free.

VDHFreeBlock Parameter - BlockToFree

BlockToFree(DD) Address of the memory block to free.

VDHFreeBlock Return Value - rc

Success If the function is successful, it returns nothing.

Failure If 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(DD) Handle (from VDHCreateBlockPool) to the pool of memory blocks that contains the memory block to free.

BlockToFree(DD) Address of the memory block to free.

VDHFreeBlock - Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: The only way to reclaim memory for freed blocks is to call VDHDestroyBlockPool.

VDHFreeBlock - Topics

Select an item:

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

EXTERN    VDHFreeDMABuffer : NEAR 
LinearAddress    DD   ?      ;    Starting   linear   address   of   the   DMA   buffer 

PUSH      LinearAddress    ;    Push   LinearAddress 

CALL      VDHFreeDMABuffer        ;   Call   the   function

VDHFreeDMABuffer - Format

/*

This   function   frees   a   DMA   buffer   previously   allocated 
by   VDHAllocDMABuffer . 
* / 

include   mvdm . inc 

EXTERN    VDHFreeDMABuffer : NEAR 
LinearAddress    DD   ?      ;    Starting   linear   address   of   the   DMA   buffer 

PUSH      LinearAddress    ;    Push   LinearAddress 

CALL      VDHFreeDMABuffer        ;   Call   the   function

VDHFreeDMABuffer Parameter - LinearAddress

LinearAddress(DD) Starting linear address of the DMA buffer.

VDHFreeDMABuffer Return Value - rc

Success If the function is successful, it returns nothing.

Failure If LinearAddressis invalid, a system halt occurs.

VDHFreeDMABuffer - Parameters

LinearAddress(DD) Starting linear address of the DMA buffer.

VDHFreeDMABuffer - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHFreeDMABuffer - Topics

Select an item:

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

EXTERN    VDHFreeHook : NEAR 
HookHandle    DD   ?      ;    Hook   handle   from   VDHAllocHook 

PUSH      HookHandle    ;    Push   HookHandle 

CALL      VDHFreeHook     ;   Call   the   function

VDHFreeHook - Format

/*

This   function   disarms   and   frees   a   hook . 
* / 

include   mvdm . inc 

EXTERN    VDHFreeHook : NEAR 
HookHandle    DD   ?      ;    Hook   handle   from   VDHAllocHook 

PUSH      HookHandle    ;    Push   HookHandle 

CALL      VDHFreeHook     ;   Call   the   function

VDHFreeHook Parameter - HookHandle

HookHandle(DD) Hook handle (from VDHAllocHook) for the hook to free.

VDHFreeHook Return Value - rc

Success If the function is successful, it returns nothing.

Failure If HookHandleis invalid, a system halt occurs.

VDHFreeHook - Parameters

HookHandle(DD) Hook handle (from VDHAllocHook) for the hook to free.

VDHFreeHook - Purpose

Context Issues: This function can be called in the initialization or DOS session-task context.

DOS Session Terminations: Any context hooks allocated in the context of the terminating DOS session are deallocated automatically by the DOS Session Manager.

VDHFreeHook - Topics

Select an item:

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

EXTERN    VDHFreeMem : NEAR 
MemAddress    DD   ?      ;    Address   of   the   memory   block   to   free 

PUSH      MemAddress    ;    Push   MemAddress 

CALL      VDHFreeMem     ;   Call   the   function

VDHFreeMem - Format

/*

This   function   frees   memory   that   was   previously   allocated   by 
VDHAllocMem . 
* / 

include   mvdm . inc 

EXTERN    VDHFreeMem : NEAR 
MemAddress    DD   ?      ;    Address   of   the   memory   block   to   free 

PUSH      MemAddress    ;    Push   MemAddress 

CALL      VDHFreeMem     ;   Call   the   function

VDHFreeMem Parameter - MemAddress

MemAddress(DD) Address of the memory block to be freed. Pointer is originally obtained from VDHAllocMem.

VDHFreeMem Return Value - rc

Success If the function is successful, it returns nothing.

Failure If MemAddressis not an address pointer allocated by VDHAllocMem, a system halt occurs.

VDHFreeMem - Parameters

MemAddress(DD) Address of the memory block to be freed. Pointer is originally obtained from VDHAllocMem.

VDHFreeMem - Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHFreeMem - Topics

Select an item:

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

EXTERN    VDHFreePages : NEAR 
ObjectAddress    DD   ?      ;    Address   of   the   memory   object   to   free 

PUSH      ObjectAddress    ;    Push   ObjectAddress 

CALL      VDHFreePages        ;   Call   the   function

VDHFreePages - Format

/*

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

include   mvdm . inc 

EXTERN    VDHFreePages : NEAR 
ObjectAddress    DD   ?      ;    Address   of   the   memory   object   to   free 

PUSH      ObjectAddress    ;    Push   ObjectAddress 

CALL      VDHFreePages        ;   Call   the   function

VDHFreePages Parameter - ObjectAddress

ObjectAddress(DD) Address of the memory object to free.

VDHFreePages Return Value - rc

Success If the function is successful, it returns nothing.

Failure If ObjectAddresswas not allocated by VDHAllocPagesor VDHReallocPages, a system halt occurs.

VDHFreePages - Parameters

ObjectAddress(DD) Address of the memory object to free.

VDHFreePages - Purpose

Context Issues: This function can be called in the initialization or task context. At initialization time, only global memory can be freed.

DOS Session Terminations: Any allocations made in the terminating DOS session's private area, or on behalf of the terminating DOS session, must be released by using VDHFreePages.

Notes: This function succeeds only if the linear range specified was allocated by a previous call to 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 
VDHThawVDM   is   called . 
This   freeze   occurs   when   the   specified   DOS   session   leaves   kernel   mode . 
The   DOS   session   does   not   execute   any   V86 - mode   code   from   the   time 
VDHFreezeVDM   is   called   until   the 
matching   VDHThawVDM   is   called . 
* / 

include   mvdm . inc 

EXTERN    VDHFreezeVDM : NEAR 
VDMHandle    DD   ?      ;    Handle   to   the   DOS   session   to   freeze 

PUSH      VDMHandle    ;    Push   VDMHandle 

CALL      VDHFreezeVDM    ;   Call   the   function

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

include   mvdm . inc 

EXTERN    VDHFreezeVDM : NEAR 
VDMHandle    DD   ?      ;    Handle   to   the   DOS   session   to   freeze 

PUSH      VDMHandle    ;    Push   VDMHandle 

CALL      VDHFreezeVDM    ;   Call   the   function

VDHFreezeVDM Parameter - VDMHandle

VDMHandle(DD) Handle to the DOS session to freeze.

VDHFreezeVDM Return Value - rc

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

Failure If the function fails, it returns 0 (zero). 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(DD) Handle to the DOS session to freeze.

VDHFreezeVDM - Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: The DOS Session Manager thaws a frozen DOS session prior to calling any VDM_TERMINATE user hooks.

Notes: Each DOS session has a freeze count. This count starts at zero when the DOS session is created. Each 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 . inc 

EXTERN    VDHGetCodePageFont : NEAR 
CellWidth      DD   ?      ;    Width   of   character   cells ,   in   pels 
CellHeight     DD   ?      ;    Height   of   character   cells ,   in   pels 
FontAddress    DD   ?      ;    Address   where   font   table   addresses   will   be   copied 

PUSH      CellWidth      ;    Push   CellWidth 
PUSH      CellHeight     ;    Push   CellHeight 
PUSH      FontAddress    ;    Push   FontAddress 

CALL      VDHGetCodePageFont      ;   Call   the   function

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

EXTERN    VDHGetCodePageFont : NEAR 
CellWidth      DD   ?      ;    Width   of   character   cells ,   in   pels 
CellHeight     DD   ?      ;    Height   of   character   cells ,   in   pels 
FontAddress    DD   ?      ;    Address   where   font   table   addresses   will   be   copied 

PUSH      CellWidth      ;    Push   CellWidth 
PUSH      CellHeight     ;    Push   CellHeight 
PUSH      FontAddress    ;    Push   FontAddress 

CALL      VDHGetCodePageFont      ;   Call   the   function

VDHGetCodePageFont Parameter - CellWidth

CellWidth(DD) Width of character cells, measured in pels.

VDHGetCodePageFont Parameter - CellHeight

CellHeight(DD) Height of character cells, measured in pels.

VDHGetCodePageFont Parameter - FontAddress

FontAddress(DD) Address to which font table addresses will be copied.

VDHGetCodePageFont Return Value - rc

Success If the function is successful, it returns the size of the font table in bytes.

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould be called to determine the nature of the problem.

VDHGetCodePageFont - Parameters

CellWidth(DD) Width of character cells, measured in pels.

CellHeight(DD) Height of character cells, measured in pels.

FontAddress(DD) Address to which font table addresses will be copied.

VDHGetCodePageFont - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: If this function was called on behalf of the terminating DOS session, 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 . inc 

EXTERN    VDHGetDirtyPageInfo : NEAR 
VDMHandle          DD   ?      ;    Handle   to   the   DOS   session   that   owns   the   object 
StartingAddress    DD   ?      ;    Address   to   start   the   scan 
PageRange          DD   ?      ;    Range   of   pages   to   scan 

PUSH      VDMHandle          ;    Push   VDMHandle 
PUSH      StartingAddress    ;    Push   StartingAddress 
PUSH      PageRange          ;    Push   PageRange 

CALL      VDHGetDirtyPageInfo          ;   Call   the   function

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

EXTERN    VDHGetDirtyPageInfo : NEAR 
VDMHandle          DD   ?      ;    Handle   to   the   DOS   session   that   owns   the   object 
StartingAddress    DD   ?      ;    Address   to   start   the   scan 
PageRange          DD   ?      ;    Range   of   pages   to   scan 

PUSH      VDMHandle          ;    Push   VDMHandle 
PUSH      StartingAddress    ;    Push   StartingAddress 
PUSH      PageRange          ;    Push   PageRange 

CALL      VDHGetDirtyPageInfo          ;   Call   the   function

VDHGetDirtyPageInfo Parameter - VDMHandle

VDMHandle(DD) Handle to the DOS session that owns the object. A 0 (zero) value indicates the current DOS session.

VDHGetDirtyPageInfo Parameter - StartingAddress

StartingAddress(DD) Starting address of the range of pages to scan.

VDHGetDirtyPageInfo Parameter - PageRange

PageRange(DD) Range (number of pages) to scan. Maximum allowed is 32.

VDHGetDirtyPageInfo Return Value - rc

Success If the function is successful, it returns the bit vector. The low- order bit (that is, bit 0, the rightmost bit) is the dirty bit for the first page scanned. Bit 1 (from the right) is the dirty bit for the next page, and so forth for all the pages scanned.

Failure If any of the input parameters are invalid, a system halt occurs.

VDHGetDirtyPageInfo - Parameters

VDMHandle(DD) Handle to the DOS session that owns the object. A 0 (zero) value indicates the current DOS session.

StartingAddress(DD) Starting address of the range of pages to scan.

PageRange(DD) Range (number of pages) to scan. Maximum allowed is 32.

VDHGetDirtyPageInfo - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: The virtual dirty bits remain set until cleared by this function, regardless of the swapping activity that has occurred. The actual dirty bits in the page tables are reset whenever a page is swapped to the swap device and brought back into memory. This function is valid only for linear addresses up to 110000H (1MB+64KB) in a DOS session.

VDHGetDirtyPageInfo - Topics

Select an item:

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

EXTERN    VDHGetError : NEAR 
     DD   ? 

PUSH           ;    Push 

CALL      VDHGet ;   Call   the   function

VDHGetError - Format

/*

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

include   mvdm . inc 

EXTERN    VDHGetError : NEAR 
     DD   ? 

PUSH           ;    Push 

CALL      VDHGet ;   Call   the   function

VDHGetError Parameter -

(DD) None.

VDHGetError Return Value - rc

Success If the function is successful, it returns the error code.

Failure If the function fails, it returns 0, indicating that the last virtual DevHlp call did not have an error.

VDHGetError - Parameters

(DD) None.

VDHGetError - Purpose

Context Issues: This function can be called in any context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: The return value is guaranteed to be valid as long as the virtual device driver does not block or yield between the virtual DevHlp service that failed and the call to VDHGetError. 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 . inc 

EXTERN    VDHGetFlags : NEAR 
ulFlagsAddr    DD   ?      ;    DOS   session   flag   address . 

PUSH      ulFlagsAddr    ;    Push   ulFlagsAddr 

CALL      VDHGetFlags      ;   Call   the   function

VDHGetFlags - Format

/*

This   function   gets   the   DOS   session ' s   EFlags   Register . 
* / 

include   mvdm . inc 

EXTERN    VDHGetFlags : NEAR 
ulFlagsAddr    DD   ?      ;    DOS   session   flag   address . 

PUSH      ulFlagsAddr    ;    Push   ulFlagsAddr 

CALL      VDHGetFlags      ;   Call   the   function

VDHGetFlags Parameter - ulFlagsAddr

ulFlagsAddr(DD) Address of the ULONG in which the EFLAGs value is to be returned.

VDHGetFlags Return Value -

None.

VDHGetFlags - Parameters

ulFlagsAddr(DD) Address of the ULONG in which the EFLAGs value is to be returned.

VDHGetFlags - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Virtual device drivers must use this interface instead of the client register frame pointer to change the DOS session's flags. Changes to the interrupt flag and the I/O Privilege Level (IOPL) field must be under the control of 8086 emulation so that 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 . inc 

EXTERN    VDHGetSelBase : NEAR 
Selector        DW   ?      ;    LDT   selector 
pBasePointer    DD   ?      ;    Pointer   for   returned   address 

PUSH      Selector        ;    Push   Selector 
PUSH      pBasePointer    ;    Push   pBasePointer 

CALL      VDHGetSelBase       ;   Call   the   function

VDHGetSelBase - Format

/*

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

include   mvdm . inc 

EXTERN    VDHGetSelBase : NEAR 
Selector        DW   ?      ;    LDT   selector 
pBasePointer    DD   ?      ;    Pointer   for   returned   address 

PUSH      Selector        ;    Push   Selector 
PUSH      pBasePointer    ;    Push   pBasePointer 

CALL      VDHGetSelBase       ;   Call   the   function

VDHGetSelBase Parameter - Selector

Selector(DW) LDT Selector.

VDHGetSelBase Parameter - pBasePointer

pBasePointer(DD) Pointer for returned address.

VDHGetSelBase Return Value - rc

Success If the function is successful, it returns a nonzero value. The base address is returned in the variable pointed to by pBasePointer.

Failure If the function fails, it returns 0 (zero).

VDHGetSelBase - Parameters

Selector(DW) LDT Selector.

pBasePointer(DD) Pointer for returned address.

VDHGetSelBase - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Error checking is performed only to ensure that the selector is allocated.

VDHGetSelBase - Topics

Select an item:

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

EXTERN    VDHGetVPMExcept : NEAR 
Vector                     DD   ?      ;    Exception   vector   number 
pHandlerAddressPointer    DD   ?      ;    Pointer   to   put   handler   address 
pFlag                      DD   ?      ;    Pointer   to   a   flag   variable 

PUSH      Vector                     ;    Push   Vector 
PUSH      pHandlerAddressPointer    ;    Push   pHandlerAddressPointer 
PUSH      pFlag                      ;    Push   pFlag 

CALL      VDHGetVPMExcept                  ;   Call   the   function

VDHGetVPMExcept - Format

/*

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

include   mvdm . inc 

EXTERN    VDHGetVPMExcept : NEAR 
Vector                     DD   ?      ;    Exception   vector   number 
pHandlerAddressPointer    DD   ?      ;    Pointer   to   put   handler   address 
pFlag                      DD   ?      ;    Pointer   to   a   flag   variable 

PUSH      Vector                     ;    Push   Vector 
PUSH      pHandlerAddressPointer    ;    Push   pHandlerAddressPointer 
PUSH      pFlag                      ;    Push   pFlag 

CALL      VDHGetVPMExcept                  ;   Call   the   function

VDHGetVPMExcept Parameter - Vector

Vector(DD) Exception vector number (0-1FH).

VDHGetVPMExcept Parameter - pHandlerAddressPointer

pHandlerAddressPointer(DD) Pointer to put handler address.

VDHGetVPMExcept Parameter - pFlag

pFlag(DD) Pointer to a flag variable for returning the flag value. Possible values are:

VPMXCPT32 A 32-bit handler was registered.
VPMXCPT_REFLECT The exception is reflected back to a V86-mode handler.

VDHGetVPMExcept Return Value - rc

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

Failure If the function fails, it returns 0.

VDHGetVPMExcept - Parameters

Vector(DD) Exception vector number (0-1FH).

pHandlerAddressPointer(DD) Pointer to put handler address.

pFlag(DD) Pointer to a flag variable for returning the flag value. Possible values are:

VPMXCPT32 A 32-bit handler was registered.
VPMXCPT_REFLECT The exception is reflected back to a V86-mode handler.

VDHGetVPMExcept - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: There must be a DPMI client running in the DOS session before calling this function.

VDHGetVPMExcept - Topics

Select an item:

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

EXTERN    VDHGetVPMIntVector : NEAR 
Vector                    DD   ?      ;    Interrupt   vector   number 
HandlerAddressPointer    DD   ?      ;    Pointer   for   return   of   handler   address 

PUSH      Vector                    ;    Push   Vector 
PUSH      HandlerAddressPointer    ;    Push   HandlerAddressPointer 

CALL      VDHGetVPMIntVector                 ;   Call   the   function

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

EXTERN    VDHGetVPMIntVector : NEAR 
Vector                    DD   ?      ;    Interrupt   vector   number 
HandlerAddressPointer    DD   ?      ;    Pointer   for   return   of   handler   address 

PUSH      Vector                    ;    Push   Vector 
PUSH      HandlerAddressPointer    ;    Push   HandlerAddressPointer 

CALL      VDHGetVPMIntVector                 ;   Call   the   function

VDHGetVPMIntVector Parameter - Vector

Vector(DD) Interrupt vector number.

VDHGetVPMIntVector Parameter - HandlerAddressPointer

HandlerAddressPointer(DD) Pointer for return of the handler address.

VDHGetVPMIntVector Return Value - rc

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

Failure If the function fails, it returns 0.

VDHGetVPMIntVector - Parameters

Vector(DD) Interrupt vector number.

HandlerAddressPointer(DD) Pointer for return of the handler address.

VDHGetVPMIntVector - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Note:There must be a DPMI client in the DOS session before calling this function.

VDHGetVPMIntVector - Topics

Select an item:

Format
Parameters 
Return Codes 
Purpose 
Glossary

VDHHaltSystem

Select an item:

Format
Parameters 
Return Codes 
Purpose 
Glossary

/*

This   function   causes   a   system   halt . 
* / 

include   mvdm . inc 

EXTERN    VDHHaltSystem : NEAR 
                DD   ? 

PUSH                      ;    Push 

CALL      VDHHaltSystem       ;   Call   the   function

VDHHaltSystem - Format

/*

This   function   causes   a   system   halt . 
* / 

include   mvdm . inc 

EXTERN    VDHHaltSystem : NEAR 
                DD   ? 

PUSH                      ;    Push 

CALL      VDHHaltSystem       ;   Call   the   function

VDHHaltSystem Parameter -

(DD) None.

VDHHaltSystem Return Value -

None.

VDHHaltSystem - Parameters

(DD) None.

VDHHaltSystem - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: Calling 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 . inc 

EXTERN    VDHHandleFromPID : NEAR 
ProcessID    DW   ?      ;    A   DOS   session   process   ID 

PUSH      ProcessID    ;    Push   ProcessID 

CALL      VDHHandleFromPID    ;   Call   the   function

VDHHandleFromPID - Format

/*

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

include   mvdm . inc 

EXTERN    VDHHandleFromPID : NEAR 
ProcessID    DW   ?      ;    A   DOS   session   process   ID 

PUSH      ProcessID    ;    Push   ProcessID 

CALL      VDHHandleFromPID    ;   Call   the   function

VDHHandleFromPID Parameter - ProcessID

ProcessID(DW) A DOS session Process ID.

VDHHandleFromPID Return Value - rc

Success If the function is successful, it returns the DOS session handle for the Process ID.

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould be called to determine the nature of the problem.

VDHHandleFromPID - Parameters

ProcessID(DW) A DOS session Process ID.

VDHHandleFromPID - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHHandleFromPID - Topics

Select an item:

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

EXTERN    VDHHandleFromSGID : NEAR 
ScreenGroupID    DW   ?      ;    Screen   Group   ID 

PUSH      ScreenGroupID    ;    Push   ScreenGroupID 

CALL      VDHHandleFromSGID        ;   Call   the   function

VDHHandleFromSGID - Format

/*

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

include   mvdm . inc 

EXTERN    VDHHandleFromSGID : NEAR 
ScreenGroupID    DW   ?      ;    Screen   Group   ID 

PUSH      ScreenGroupID    ;    Push   ScreenGroupID 

CALL      VDHHandleFromSGID        ;   Call   the   function

VDHHandleFromSGID Parameter - ScreenGroupID

ScreenGroupID(DW) Screen Group ID.

VDHHandleFromSGID Return Value - rc

Success If the function is successful, it returns a handle to the DOS session that was given the Screen Group ID.

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould be called to determine the nature of the problem.

VDHHandleFromSGID - Parameters

ScreenGroupID(DW) Screen Group ID.

VDHHandleFromSGID - Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHHandleFromSGID - Topics

Select an item:

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

EXTERN    VDHInstallFaultHook : NEAR 
VDMHandle                  DD   ?      ;    DOS   session   handle ;   0   =   current   DOS   session 
StartingAddress           DD   ?      ;    Starting   linear   address 
Pages                      DD   ?      ;    Number   of   pages 
PageFaultHandlerFcnPtr    DD   ?      ;    Page   fault   handler   function 
OptionFlag                 DD   ?      ;    Options   bit   flag 

PUSH      VDMHandle                  ;    Push   VDMHandle 
PUSH      StartingAddress           ;    Push   StartingAddress 
PUSH      Pages                      ;    Push   Pages 
PUSH      PageFaultHandlerFcnPtr    ;    Push   PageFaultHandlerFcnPtr 
PUSH      OptionFlag                 ;    Push   OptionFlag 

CALL      VDHInstallFaultHook                  ;   Call   the   function

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

EXTERN    VDHInstallFaultHook : NEAR 
VDMHandle                  DD   ?      ;    DOS   session   handle ;   0   =   current   DOS   session 
StartingAddress           DD   ?      ;    Starting   linear   address 
Pages                      DD   ?      ;    Number   of   pages 
PageFaultHandlerFcnPtr    DD   ?      ;    Page   fault   handler   function 
OptionFlag                 DD   ?      ;    Options   bit   flag 

PUSH      VDMHandle                  ;    Push   VDMHandle 
PUSH      StartingAddress           ;    Push   StartingAddress 
PUSH      Pages                      ;    Push   Pages 
PUSH      PageFaultHandlerFcnPtr    ;    Push   PageFaultHandlerFcnPtr 
PUSH      OptionFlag                 ;    Push   OptionFlag 

CALL      VDHInstallFaultHook                  ;   Call   the   function

VDHInstallFaultHook Parameter - VDMHandle

VDMHandle(DD) DOS session handle. If the parameter contains a 0 (zero), use the currently active DOS session.

VDHInstallFaultHook Parameter - StartingAddress

StartingAddress(DD) Starting linear address.

VDHInstallFaultHook Parameter - Pages

Pages(DD) Number of pages.

VDHInstallFaultHook Parameter - PageFaultHandlerFcnPtr

PageFaultHandlerFcnPtr(DD) Page fault handler function.

The PageFaultHandlerFcnPtr function pointer contains the address of a function with the following interface:

PageFaultHandler  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pVDM - Address of the page in which fault occurred
;    EXIT   None
;
; CONTEXT   DOS session-task

VDHInstallFaultHook Parameter - OptionFlag

OptionFlag(DD) Options bit flag.

Possible value:

VDHIFH_ADDR If set, pVDM is a byte-granular address. Otherwise, pVDM is a page-granular address.

VDHInstallFaultHook Return Value - rc

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

Failure If the function fails, it returns 0 (zero). VDHGetError should be called to determine the nature of the problem. If any of the input parameters are invalid, a system halt occurs.

VDHInstallFaultHook - Parameters

VDMHandle(DD) DOS session handle. If the parameter contains a 0 (zero), use the currently active DOS session.

StartingAddress(DD) Starting linear address.

Pages(DD) Number of pages.

PageFaultHandlerFcnPtr(DD) Page fault handler function.

The PageFaultHandlerFcnPtr function pointer contains the address of a function with the following interface:

PageFaultHandler  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pVDM - Address of the page in which fault occurred
;    EXIT   None
;
; CONTEXT   DOS session-task

OptionFlag(DD) Options bit flag.

Possible value:

VDHIFH_ADDR If set, pVDM is a byte-granular address. Otherwise, pVDM is a page-granular address.

VDHInstallFaultHook - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: Any fault hooks for the terminating DOS session must be released by using VDHRemoveFaultHook.

Notes: In order for the fault handler to terminate the DOS session, it must call VDHKillVDM and return. Page fault hooks are stored on a per-DOS session basis.

VDHInstallFaultHook - Topics

Select an item:

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

EXTERN    VDHInstallIntHook : NEAR 
Reserved      DD   ?      ;    Reserved ;   must   be   set   to   0 
Vector        DD   ?      ;    Number   of   the   interrupt   vector   to   hook 
HookFcn       DD   ?      ;    Address   of   the   hook   routine 
OptionFlag    DD   ?      ;    Interface   options   flag 

PUSH      Reserved      ;    Push   Reserved 
PUSH      Vector        ;    Push   Vector 
PUSH      HookFcn       ;    Push   HookFcn 
PUSH      OptionFlag    ;    Push   OptionFlag 

CALL      VDHInstallIntHook     ;   Call   the   function

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

EXTERN    VDHInstallIntHook : NEAR 
Reserved      DD   ?      ;    Reserved ;   must   be   set   to   0 
Vector        DD   ?      ;    Number   of   the   interrupt   vector   to   hook 
HookFcn       DD   ?      ;    Address   of   the   hook   routine 
OptionFlag    DD   ?      ;    Interface   options   flag 

PUSH      Reserved      ;    Push   Reserved 
PUSH      Vector        ;    Push   Vector 
PUSH      HookFcn       ;    Push   HookFcn 
PUSH      OptionFlag    ;    Push   OptionFlag 

CALL      VDHInstallIntHook     ;   Call   the   function

VDHInstallIntHook Parameter - Reserved

Reserved(DD) Reserved. Must be set to 0.

VDHInstallIntHook Parameter - Vector

Vector(DD) Number of the interrupt vector to hook (0-255).

VDHInstallIntHook Parameter - HookFcn

HookFcn(DD) Address of the hook routine.

VDHInstallIntHook Parameter - OptionFlag

OptionFlag(DD) Interface options flag.

Possible values:

VDH_ASM_HOOK Use assembler language hook interface (for the assembler language interface refer to the function 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

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(DD) Reserved. Must be set to 0.

Vector(DD) Number of the interrupt vector to hook (0-255).

HookFcn(DD) Address of the hook routine.

OptionFlag(DD) Interface options flag.

Possible values:

VDH_ASM_HOOK Use assembler language hook interface (for the assembler language interface refer to the function 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 - 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 . inc 

EXTERN    VDHInstallIOHook : NEAR 
Reserved           DD   ?      ;    Reserved ;   must   be   set   to   0 
StartingPort       DD   ?      ;    Starting   port   number 
NumPorts           DD   ?      ;    The   number   of   ports   from   the   starting   point 
IOPortHookEntry    DD   ?      ;    Pointer   to   I / O   port   hook   entry 
Flags               DD   ?      ;    Indicates   interface   and   trapping   options 

PUSH      Reserved           ;    Push   Reserved 
PUSH      StartingPort       ;    Push   StartingPort 
PUSH      NumPorts           ;    Push   NumPorts 
PUSH      IOPortHookEntry    ;    Push   IOPortHookEntry 
PUSH      Flags               ;    Push   Flags 

CALL      VDHInstallIOHook          ;   Call   the   function

VDHInstallIOHook - Format

/*

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

include   mvdm . inc 

EXTERN    VDHInstallIOHook : NEAR 
Reserved           DD   ?      ;    Reserved ;   must   be   set   to   0 
StartingPort       DD   ?      ;    Starting   port   number 
NumPorts           DD   ?      ;    The   number   of   ports   from   the   starting   point 
IOPortHookEntry    DD   ?      ;    Pointer   to   I / O   port   hook   entry 
Flags               DD   ?      ;    Indicates   interface   and   trapping   options 

PUSH      Reserved           ;    Push   Reserved 
PUSH      StartingPort       ;    Push   StartingPort 
PUSH      NumPorts           ;    Push   NumPorts 
PUSH      IOPortHookEntry    ;    Push   IOPortHookEntry 
PUSH      Flags               ;    Push   Flags 

CALL      VDHInstallIOHook          ;   Call   the   function

VDHInstallIOHook Parameter - Reserved

Reserved(DD) Reserved. Must be set to 0 (zero).

VDHInstallIOHook Parameter - StartingPort

StartingPort(DD) Number of the starting port.

VDHInstallIOHook Parameter - NumPorts

NumPorts(DD) The number of ports from the starting port.

VDHInstallIOHook Parameter - IOPortHookEntry

IOPortHookEntry(DD) Pointer to I/O port hook entry.

VDHInstallIOHook Parameter - Flags

Flags(DD) Indicates interface and trapping options.

Possible values:

VDHIIH_ASM_HOOK Use assembler language hook interface (register-based). Otherwise, use a C hook interface (stack-based).

VDHIIH_ALWAYS_TRAP Always trap this range of addresses. The virtual device driver cannot call VDHSetIOHookState on any ports in the range.

VDHIIH_NO_SIMULATE Does not change WORD or other I/O handlers to simulation routines; allows WORD handlers for 1-port ranges.

VDHIIH_IGNORE Sets a system handler that does the following:

On WRITES: The OUT succeeds, but no actual I/O is performed.
On READS: The IN succeeds, and always returns -1 (all bits set to 1).

This is also the default behavior of unhooked ports. This behavior is compatible with the behavior of a machine when there is no hardware on a particular I/O address.

VDHInstallIOHook Return Value - rc

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

Failure If the function fails, it returns 0 (zero). 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(DD) Reserved. Must be set to 0 (zero).

StartingPort(DD) Number of the starting port.

NumPorts(DD) The number of ports from the starting port.

IOPortHookEntry(DD) Pointer to I/O port hook entry.

Flags(DD) Indicates interface and trapping options.

Possible values:

VDHIIH_ASM_HOOK Use assembler language hook interface (register-based). Otherwise, use a C hook interface (stack-based).

VDHIIH_ALWAYS_TRAP Always trap this range of addresses. The virtual device driver cannot call VDHSetIOHookState on any ports in the range.

VDHIIH_NO_SIMULATE Does not change WORD or other I/O handlers to simulation routines; allows WORD handlers for 1-port ranges.

VDHIIH_IGNORE Sets a system handler that does the following:

On WRITES: The OUT succeeds, but no actual I/O is performed.
On READS: The IN succeeds, and always returns -1 (all bits set to 1).

This is also the default behavior of unhooked ports. This behavior is compatible with the behavior of a machine when there is no hardware on a particular I/O address.

VDHInstallIOHook - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function. I/O hooks are automatically removed during DOS session termination.

Notes: This function installs I/O port trap handlers for a contiguous range of I/O addresses. Trapping is initially enabled for the specified ports. The I/O hook entry contains the handlers for each kind of I/O operation. If an entry in the table is NULL, that I/O type is simulated by using a lower I/O type (for example, WORD-I/O is simulated by performing two-byte I/O operations). I/O port hooks are kept on a per-DOS session basis; a virtual device driver generally installs I/O hooks at DOS session creation time.

VDHSetIOHookState can be used to enable or disable I/O trapping on a per- port, per-DOS session basis except when the VDHIIH_ALWAYS_TRAP option is specified. In this case, VDHSetIOHookState cannot be called on any port in the range for the current DOS session.

I/O hooks can take their parameters either from registers or the stack. High-performance hooks take register parameters (the I/O hook router is optimized for this case). Hooks with lower performance requirements take stack parameters, and therefore can be written in the C language.

WordInput, WordOutput and Other hooks can be NULL. In this case, the DOS Session Manager simulates these routines by using the ByteInput and ByteOutput routines. If the ByteInput or ByteOutput handlers are NULL, the DOS Session Manager uses default internal routines that do input and output to the hardware ports. This is most useful when a virtual device driver shadows the hardware state (by trapping OUT instructions) but does not care what is returned by IN instructions.

The client register frame (CRF) is updated as the instructions are simulated. For example, when the string I/O instructions are simulated, the client's EDI/ESI and ECX is incremented or decremented.

In a particular DOS session, a particular I/O port address can be hooked only by a single virtual device driver. If this function fails, no I/O hooks are installed.

The routing of I/O instructions to the supplied port hooks covers the specified range exactly. If an I/O instruction overlaps port address ranges hooked on separate VDHInstallIOHook calls, the instruction is simulated with smaller I/O operations to ensure that the hooks in each range are called correctly. For example, a virtual device driver that hooks 100H-103H , and installs a byte, WORD, and DWORD (other) handler would work as follows:

    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:

ioh STRUC
    ioh_pbihByteInput    DD   ?
    ioh_pbohByteOutput   DD   ?
    ioh_pwihWordInput    DD   ?
    ioh_pwohWordOutput   DD   ?
    ioh_pothOther        DD   ?
ioh ENDS

ByteInput  PROC  NEAR
; PARAMETERS
;    ENTRY  - port - Port number
;           - pcrf - Client register frame pointer
;    EXIT   Data read returned in AL
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

ByteOutput  PROC  NEAR
; PARAMETERS
;    ENTRY  - bOutputData - Data to write
;           - port        - Port number
;           - pcrf        - Client register frame pointer
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

WordInput  PROC  NEAR
; PARAMETERS
;    ENTRY  - port - Port number
;           - pcrf - Client register frame pointer
;    EXIT   Data read returned in AX
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

WordOutput  PROC  NEAR
; PARAMETERS
;    ENTRY   - usOutputData - Data to write
;            - port         - Port number
;            - pcrf         - Client register frame pointer
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

OtherHook  PROC  NEAR
; PARAMETERS
;    ENTRY  EAX - ulOutputData         - Data for DWORD writes
;           [ESP + 16] - pulInputData  - Pointer to put input data
;                        (See NOTE, below)
;           EDX - port                 - Port number
;           ECX - flType               - I/O type
;               IO_TYPE_SHIFT          - Shift for type
;               IO_TYPE_MASK           - Mask for type
;               IO_TYPE_INPUT          - If set input else output
;               IO_TYPE_BYTE           - If set byte else WORD/DWORD
;               IO_TYPE_DWORD
;               IO_TYPE_STRING
;               IO_TYPE_REVERSE
;               IO_TYPE_ADDR32
;               IO_TYPE_REP
;               IO_SEG_SHIFT           - Shift for SEG  field
;               IO_SEG_MASK      - Mask for SEG field
;               IO_SEG_CS
;               IO_SEG_SS
;               IO_SEG_ES
;               IO_SEG_FS
;               IO_SEG_GS
;           EBX - pcrf           - Client register frame pointer
;    EXIT   If assembly language hook,
;              EAX - Data from DWORD reads
;              If carry flag set, simulate the I/O operation
;              If carry flag clear, I/O is done
;           If C hook
;              *pulInputData - Data from DWORD reads
;              If returns 0 in EAX, simulate the I/O operation
;              If returns a non-zero value in EAX, I/O is done
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task
; NOTES     The ASM OtherHook hook does not need the pulInputData parameter
;           because it returns DWORD input values in EAX, with the
;           carry flag used to indicate done/simulate.
;           The C hook has to use EAX to return status, and so needs the
;           additional parameter.

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

EXTERN    VDHInstallUserHook : NEAR 
Event       DD   ?      ;    A   DOS   session   event   for   which   a   handler   is   installed 
UserHook    DD   ?      ;    User ' s   handler   for   this   event 

PUSH      Event       ;    Push   Event 
PUSH      UserHook    ;    Push   UserHook 

CALL      VDHInstallUserHook   ;   Call   the   function

VDHInstallUserHook - Format

/*

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

include   mvdm . inc 

EXTERN    VDHInstallUserHook : NEAR 
Event       DD   ?      ;    A   DOS   session   event   for   which   a   handler   is   installed 
UserHook    DD   ?      ;    User ' s   handler   for   this   event 

PUSH      Event       ;    Push   Event 
PUSH      UserHook    ;    Push   UserHook 

CALL      VDHInstallUserHook   ;   Call   the   function

VDHInstallUserHook Parameter - Event

Event(DD) A DOS session event (such as DOS session termination).

Possible values are:

VDD_EXIT DOS session support is shutting down
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:

pfnCreate  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT   SUCCESS  Return a non-zero value
;           FAILURE  Return 0
;                    DOS session creation fails; the DOS Session Manager calls
;                    all the VDM_TERMINATE hooks for all virtual
;                    device drivers that returned SUCCESS on this
;                    DOS session creation.
;
;
; CONTEXT   DOS session-task

pfnTerminate  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session being terminated
;    EXIT   None
;
; CONTEXT   DOS session-task

pfnForeground  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session coming to the foreground
;    EXIT   None
;
; CONTEXT   Task

pfnBackground  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session going to the background
;    EXIT   None
;
; CONTEXT   Task

pfnExit  PROC  NEAR
; PARAMETERS
;    ENTRY  None
;    EXIT   None
;
; CONTEXT   Initialization and Task

pfnCreateDone  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT   None
;
; CONTEXT   DOS session creation

pfnVDDCreateDone  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT   None
;
; CONTEXT   DOS session Creation

pfnPDBDestroyed  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm    - Handle to DOS session
;           [ESP + 4] - segPDB  - V86 segment of terminating PDB
;    EXIT   None
;
; CONTEXT   DOS session-task

pfnPDBSwitched  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm   - Handle to DOS session
;           [ESP + 4] - segPDB - V86 segment of new PDB
;    EXIT   None
;
; CONTEXT   DOS session-task

pfnCodePageChanged  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - ulCodePage - New code page
;    EXIT   SUCCESS  Return a non-zero value in EAX
;           FAILURE  Return 0 in EAX
;                    An error is returned on the set code-page operation, but
;                    the rest of the device-code-page handlers are called.
;
; CONTEXT   DOS session-task

pfnVDMTitleChange  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pszTitle - new DOS session Title
;    EXIT   SUCCESS  Return a non-zero value in EAX
;           FAILURE  Return 0 in EAX
;
; CONTEXT   DOS session-task
; NOTES     1. This event is called for both full screen and windowed DOS session.
;           2. If pszTitle is NULL, the virtual device driver should treat it
;              as the DOS session's default and original title.
;           3. Ideally there should be only one virtual device driver for this
;              hook, but this is not a restriction.  One of the virtual device
;              drivers registered is responsible for putting the title.  Only
;              this virtual device driver returns a non-zero value, all others
;              return 0.

pfnMemoryMappedIn  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - hvdm   - Handle to DOS session
;           [ESP + 12] - page   - Page address
;           [ESP +  8] - cpages - Number of pages mapped in from
;                             the starting page address
;           [ESP +  4] - fl     - Type of mapping, (see VDHMapPages)
;    EXIT   SUCCESS  Return a non-zero value in EAX
;           FAILURE  Return 0 in EAX
;
; CONTEXT   DOS session-task

pfnMemoryUnMapped  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - hvdm   - Handle to DOS session
;           [ESP + 12] - page   - Page address
;           [ESP +  8] - cpages - Number of pages unmapped from
;                                                     the starting page address
;           [ESP +  4] - fl     - Type of mapping, (see VDHMapPages)
;    EXIT   SUCCESS  Return a non-zero value in EAX
;           FAILURE  Return 0 in EAX
;
; CONTEXT   DOS session-task

VDHInstallUserHook Parameter - UserHook

UserHook(DD) A user-defined handler for the event.

VDHInstallUserHook Return Value - rc

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

Failure If the function fails, an invalid input parameter or a kernel heap overflow (that is, if the system runs out of memory) causes a system halt.

VDHInstallUserHook - Parameters

Event(DD) A DOS session event (such as DOS session termination).

Possible values are:

VDD_EXIT DOS session support is shutting down
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:

pfnCreate  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT   SUCCESS  Return a non-zero value
;           FAILURE  Return 0
;                    DOS session creation fails; the DOS Session Manager calls
;                    all the VDM_TERMINATE hooks for all virtual
;                    device drivers that returned SUCCESS on this
;                    DOS session creation.
;
;
; CONTEXT   DOS session-task

pfnTerminate  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session being terminated
;    EXIT   None
;
; CONTEXT   DOS session-task

pfnForeground  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session coming to the foreground
;    EXIT   None
;
; CONTEXT   Task

pfnBackground  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - DOS session going to the background
;    EXIT   None
;
; CONTEXT   Task

pfnExit  PROC  NEAR
; PARAMETERS
;    ENTRY  None
;    EXIT   None
;
; CONTEXT   Initialization and Task

pfnCreateDone  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT   None
;
; CONTEXT   DOS session creation

pfnVDDCreateDone  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - hvdm - Handle to DOS session
;    EXIT   None
;
; CONTEXT   DOS session Creation

pfnPDBDestroyed  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm    - Handle to DOS session
;           [ESP + 4] - segPDB  - V86 segment of terminating PDB
;    EXIT   None
;
; CONTEXT   DOS session-task

pfnPDBSwitched  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm   - Handle to DOS session
;           [ESP + 4] - segPDB - V86 segment of new PDB
;    EXIT   None
;
; CONTEXT   DOS session-task

pfnCodePageChanged  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - ulCodePage - New code page
;    EXIT   SUCCESS  Return a non-zero value in EAX
;           FAILURE  Return 0 in EAX
;                    An error is returned on the set code-page operation, but
;                    the rest of the device-code-page handlers are called.
;
; CONTEXT   DOS session-task

pfnVDMTitleChange  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pszTitle - new DOS session Title
;    EXIT   SUCCESS  Return a non-zero value in EAX
;           FAILURE  Return 0 in EAX
;
; CONTEXT   DOS session-task
; NOTES     1. This event is called for both full screen and windowed DOS session.
;           2. If pszTitle is NULL, the virtual device driver should treat it
;              as the DOS session's default and original title.
;           3. Ideally there should be only one virtual device driver for this
;              hook, but this is not a restriction.  One of the virtual device
;              drivers registered is responsible for putting the title.  Only
;              this virtual device driver returns a non-zero value, all others
;              return 0.

pfnMemoryMappedIn  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - hvdm   - Handle to DOS session
;           [ESP + 12] - page   - Page address
;           [ESP +  8] - cpages - Number of pages mapped in from
;                             the starting page address
;           [ESP +  4] - fl     - Type of mapping, (see VDHMapPages)
;    EXIT   SUCCESS  Return a non-zero value in EAX
;           FAILURE  Return 0 in EAX
;
; CONTEXT   DOS session-task

pfnMemoryUnMapped  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - hvdm   - Handle to DOS session
;           [ESP + 12] - page   - Page address
;           [ESP +  8] - cpages - Number of pages unmapped from
;                                                     the starting page address
;           [ESP +  4] - fl     - Type of mapping, (see VDHMapPages)
;    EXIT   SUCCESS  Return a non-zero value in EAX
;           FAILURE  Return 0 in EAX
;
; CONTEXT   DOS session-task

UserHook(DD) A user-defined handler for the event.

VDHInstallUserHook - Purpose

Context Issues: This function can be called only in the initialization context.

DOS Sessions Terminations: The VDM_TERMINATE hook is called at DOS session termination. In the case of a partially created DOS session, the VDM_ TERMINATE handler is called only if all the registered VDM_CREATE handlers are called successfully. Partially created DOS sessions might occur when, for example, the Create_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 . inc 

EXTERN    VDHIsVDMFrozen : NEAR 
VDMHandle    DD   ?      ;    Handle   to   the   DOS   session 

PUSH      VDMHandle    ;    Push   VDMHandle 

CALL      VDHIsVDMFrozen    ;   Call   the   function

VDHIsVDMFrozen - Format

/*

This   function   returns   the   freeze   state   of   a   DOS   session . 
* / 

include   mvdm . inc 

EXTERN    VDHIsVDMFrozen : NEAR 
VDMHandle    DD   ?      ;    Handle   to   the   DOS   session 

PUSH      VDMHandle    ;    Push   VDMHandle 

CALL      VDHIsVDMFrozen    ;   Call   the   function

VDHIsVDMFrozen Parameter - VDMHandle

VDMHandle(DD) Handle to the DOS session in question.

VDHIsVDMFrozen Return Value - rc

Success If the DOS session is not frozen, the function returns 0 (zero). Otherwise, the function returns a nonzero value indicating the DOS session' s freeze count.

Failure If VDMHandleis an invalid DOS session handle, a system halt occurs .

VDHIsVDMFrozen - Parameters

VDMHandle(DD) Handle to the DOS session in question.

VDHIsVDMFrozen - Purpose

Context Issues: This function can be called in the task or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: See 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 . inc 

EXTERN    VDHKillVDM : NEAR 
VDMHandle    DD   ?      ;    Handle   to   the   DOS   session   to   terminate 

PUSH      VDMHandle    ;    Push   VDMHandle 

CALL      VDHKillVDM    ;   Call   the   function

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

EXTERN    VDHKillVDM : NEAR 
VDMHandle    DD   ?      ;    Handle   to   the   DOS   session   to   terminate 

PUSH      VDMHandle    ;    Push   VDMHandle 

CALL      VDHKillVDM    ;   Call   the   function

VDHKillVDM Parameter - VDMHandle

VDMHandle(DD) Handle to the DOS session to terminate. A value of 0 (zero) indicates the current DOS session.

VDHKillVDM Return Value - rc

Success If the function is successful, it returns nothing.

Failure If VDMHandleis not a valid DOS session handle, a system halt occurs.

VDHKillVDM - Parameters

VDMHandle(DD) Handle to the DOS session to terminate. A value of 0 (zero) indicates the current DOS session.

VDHKillVDM - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: When a DOS session is terminating, all virtual device drivers that registered a VDM_TERMINATE hook by using 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 . inc 

EXTERN    VDHLockMem : NEAR 
StartingLinAddr     DD   ?      ;    Starting   address   of   region   in   user   process 
NumBytes            DD   ?      ;    The   size   of   the   region   to   lock ,   in   bytes . 
OptionFlag          DD   ?      ;    Access   option   flags 
PagelistArrayPtr    DD   ?      ;    Pointer   to   array   of   VDHPageList _ s   structures 
ArrayCountPtr       DD   ?      ;    Points   to   count   of   VDHPageList _ selements 

PUSH      StartingLinAddr     ;    Push   StartingLinAddr 
PUSH      NumBytes            ;    Push   NumBytes 
PUSH      OptionFlag          ;    Push   OptionFlag 
PUSH      PagelistArrayPtr    ;    Push   PagelistArrayPtr 
PUSH      ArrayCountPtr       ;    Push   ArrayCountPtr 

CALL      VDHLockMem           ;   Call   the   function

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

EXTERN    VDHLockMem : NEAR 
StartingLinAddr     DD   ?      ;    Starting   address   of   region   in   user   process 
NumBytes            DD   ?      ;    The   size   of   the   region   to   lock ,   in   bytes . 
OptionFlag          DD   ?      ;    Access   option   flags 
PagelistArrayPtr    DD   ?      ;    Pointer   to   array   of   VDHPageList _ s   structures 
ArrayCountPtr       DD   ?      ;    Points   to   count   of   VDHPageList _ selements 

PUSH      StartingLinAddr     ;    Push   StartingLinAddr 
PUSH      NumBytes            ;    Push   NumBytes 
PUSH      OptionFlag          ;    Push   OptionFlag 
PUSH      PagelistArrayPtr    ;    Push   PagelistArrayPtr 
PUSH      ArrayCountPtr       ;    Push   ArrayCountPtr 

CALL      VDHLockMem           ;   Call   the   function

VDHLockMem Parameter - StartingLinAddr

StartingLinAddr(DD) Starting linear address of the region in the user process that is to be locked.

VDHLockMem Parameter - NumBytes

NumBytes(DD) Size in bytes of the region to lock.

VDHLockMem Parameter - OptionFlag

OptionFlag(DD) Used to set access options for the locked region. The VDHLM _READ and VDHLM_WRITE flags are for verification purposes and are not mixed with the VDHLM_RESIDENT flag. Either the VDHLM_READ, VDHLM_WRITE, or VDHLM_ RESIDENT flag must be used. Note that VDHLM_RESIDENT cannot be combined with other flags.

Possible values are:

VDHLM_RESIDENT Lock physical pages.

VDHLM_READ Verify read access. VDHLM_READ is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.

VDHLM_WRITE Verify write access. VDHLM_WRITE is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.

VDHLM_CONTIGUOUS Force physical pages contiguous; can be used only for 64KB or less.

VDHLM_NOBLOCK Lock must not give up the CPU.

VDHLM_16M Must reside below the 16MB physical memory address.

VDHLockMem Parameter - PagelistArrayPtr

PagelistArrayPtr(DD) Pointer to array of VDHPageList_s structures.

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(DD) 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

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(DD) Starting linear address of the region in the user process that is to be locked.

NumBytes(DD) Size in bytes of the region to lock.

OptionFlag(DD) Used to set access options for the locked region. The VDHLM _READ and VDHLM_WRITE flags are for verification purposes and are not mixed with the VDHLM_RESIDENT flag. Either the VDHLM_READ, VDHLM_WRITE, or VDHLM_ RESIDENT flag must be used. Note that VDHLM_RESIDENT cannot be combined with other flags.

Possible values are:

VDHLM_RESIDENT Lock physical pages.

VDHLM_READ Verify read access. VDHLM_READ is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.

VDHLM_WRITE Verify write access. VDHLM_WRITE is a verify lock, and is not mixed with other flags. Nonverify locks always make the region resident.

VDHLM_CONTIGUOUS Force physical pages contiguous; can be used only for 64KB or less.

VDHLM_NOBLOCK Lock must not give up the CPU.

VDHLM_16M Must reside below the 16MB physical memory address.

PagelistArrayPtr(DD) Pointer to array of VDHPageList_s structures.

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(DD) 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 - 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 . inc 

EXTERN    VDHMapPages : NEAR 
pvdhmsSourceRegion    DD   ?      ;    Pointer   to   source   region   definition 
pvdhmtTargetRegion    DD   ?      ;    Target   region   definition 
flMappingFlag         DD   ?      ;    Mapping   options   flag 

PUSH      pvdhmsSourceRegion    ;    Push   pvdhmsSourceRegion 
PUSH      pvdhmtTargetRegion    ;    Push   pvdhmtTargetRegion 
PUSH      flMappingFlag         ;    Push   flMappingFlag 

CALL      VDHMapPages              ;   Call   the   function

VDHMapPages - Format

/*

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

include   mvdm . inc 

EXTERN    VDHMapPages : NEAR 
pvdhmsSourceRegion    DD   ?      ;    Pointer   to   source   region   definition 
pvdhmtTargetRegion    DD   ?      ;    Target   region   definition 
flMappingFlag         DD   ?      ;    Mapping   options   flag 

PUSH      pvdhmsSourceRegion    ;    Push   pvdhmsSourceRegion 
PUSH      pvdhmtTargetRegion    ;    Push   pvdhmtTargetRegion 
PUSH      flMappingFlag         ;    Push   flMappingFlag 

CALL      VDHMapPages              ;   Call   the   function

VDHMapPages Parameter - pvdhmsSourceRegion

pvdhmsSourceRegion(DD) Pointer to VDHMAPSOURCE structure.

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

VDHMapSource_s STRUC
    vdhms_laddr   DD   ?   ; Source linear address of source memory object.
                           ; Source address to be mapped.  Defines the
                           ; start of the source region for the mapping.
                           ; The region is the same length as the target
                           ; region.
    vdhms_hobj    DD   ?   ; Memory object handle set by the service to
                           ; hold a source handle for VDHMT_LINEAR
                           ; mappings. See the VDHMT_LINEAR description
                           ; under MappingFlag.
VDHMapSource_s ENDS

VDHMapPages Parameter - pvdhmtTargetRegion

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

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

VDHMapTarget_s STRUC
    vdhmt_laddr   DD  ? ; Address in V86-space to be mapped
                           ; (0 <= vdhmt_laddr < 1MB+64KB)
    vdhmt_cpg     DD  ? ; Count of pages to map
    vdhmt_hmap    DD  ? ; Mapping handle.  Must be zero on the first call to
                           ; VDHMapPages for region.  Set by the service to
                           ; hold a handle used for remapping the region. The
                           ; handle is reset each time it is used.  vdhmt_hmap
                           ; must be the value returned from the previous
                           ; VDHMapPages call for the region unless the pages
                           ; are either already invalid or else are being made
                           ; invalid.  If either the old or new mapping is
                           ; invalid pages, vdhmt_hmap can be 0. Making a
                           ; region invalid restores pages in the region to
                           ; their reserved state, and sets vdhmt_hmap to 0.
VDHMapTarget_s ENDS

VDHMapPages Parameter - flMappingFlag

flMappingFlag(DD) 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

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(DD) Pointer to VDHMAPSOURCE structure.

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

VDHMapSource_s STRUC
    vdhms_laddr   DD   ?   ; Source linear address of source memory object.
                           ; Source address to be mapped.  Defines the
                           ; start of the source region for the mapping.
                           ; The region is the same length as the target
                           ; region.
    vdhms_hobj    DD   ?   ; Memory object handle set by the service to
                           ; hold a source handle for VDHMT_LINEAR
                           ; mappings. See the VDHMT_LINEAR description
                           ; under MappingFlag.
VDHMapSource_s ENDS

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

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

VDHMapTarget_s STRUC
    vdhmt_laddr   DD  ? ; Address in V86-space to be mapped
                           ; (0 <= vdhmt_laddr < 1MB+64KB)
    vdhmt_cpg     DD  ? ; Count of pages to map
    vdhmt_hmap    DD  ? ; Mapping handle.  Must be zero on the first call to
                           ; VDHMapPages for region.  Set by the service to
                           ; hold a handle used for remapping the region. The
                           ; handle is reset each time it is used.  vdhmt_hmap
                           ; must be the value returned from the previous
                           ; VDHMapPages call for the region unless the pages
                           ; are either already invalid or else are being made
                           ; invalid.  If either the old or new mapping is
                           ; invalid pages, vdhmt_hmap can be 0. Making a
                           ; region invalid restores pages in the region to
                           ; their reserved state, and sets vdhmt_hmap to 0.
VDHMapTarget_s ENDS

flMappingFlag(DD) 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 - 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   DosOpen   API . 
Refer   to   the 
OS / 2   Control   Program   Programming   Reference 
for   a   complete   descriptions   of   each   DosOpen   API   parameter . 
* / 

include   mvdm . inc 

EXTERN    VDHOpen : NEAR 
FileName         DD   ?      ;    Pointer   to   the   name   of   the   file   or   device   to   open 
FileHandle       DD   ?      ;    Where   the   system   returns   the   file   handle 
ActionTaken      DD   ?      ;    Where   a   description   of   the   action   taken   is   returned 
FileSize         DD   ?      ;    The   new   file ' s   logical   size   ( EOD )   in   bytes 
FileAttribute    DD   ?      ;    File   attribute   bits   used   on   file   creation 
OpenFLag         DD   ?      ;    Specifies   action   taken ,   based   on   whether   file   exists 
OpenMode         DD   ?      ;    Describes   the   mode   of   the   Open   function 
EABuf            DD   ?      ;    Address   of   a   VDH _ EAOP   structure   or   NULL 

PUSH      FileName         ;    Push   FileName 
PUSH      FileHandle       ;    Push   FileHandle 
PUSH      ActionTaken      ;    Push   ActionTaken 
PUSH      FileSize         ;    Push   FileSize 
PUSH      FileAttribute    ;    Push   FileAttribute 
PUSH      OpenFLag         ;    Push   OpenFLag 
PUSH      OpenMode         ;    Push   OpenMode 
PUSH      EABuf            ;    Push   EABuf 

CALL      VDHOpen        ;   Call   the   function

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

include   mvdm . inc 

EXTERN    VDHOpen : NEAR 
FileName         DD   ?      ;    Pointer   to   the   name   of   the   file   or   device   to   open 
FileHandle       DD   ?      ;    Where   the   system   returns   the   file   handle 
ActionTaken      DD   ?      ;    Where   a   description   of   the   action   taken   is   returned 
FileSize         DD   ?      ;    The   new   file ' s   logical   size   ( EOD )   in   bytes 
FileAttribute    DD   ?      ;    File   attribute   bits   used   on   file   creation 
OpenFLag         DD   ?      ;    Specifies   action   taken ,   based   on   whether   file   exists 
OpenMode         DD   ?      ;    Describes   the   mode   of   the   Open   function 
EABuf            DD   ?      ;    Address   of   a   VDH _ EAOP   structure   or   NULL 

PUSH      FileName         ;    Push   FileName 
PUSH      FileHandle       ;    Push   FileHandle 
PUSH      ActionTaken      ;    Push   ActionTaken 
PUSH      FileSize         ;    Push   FileSize 
PUSH      FileAttribute    ;    Push   FileAttribute 
PUSH      OpenFLag         ;    Push   OpenFLag 
PUSH      OpenMode         ;    Push   OpenMode 
PUSH      EABuf            ;    Push   EABuf 

CALL      VDHOpen        ;   Call   the   function

VDHOpen Parameter - FileName

FileName(DD) Pointer to the ASCIIZ string containing the name of the device or file to open.

VDHOpen Parameter - FileHandle

FileHandle(DD) Where the system returns the file handle.

VDHOpen Parameter - ActionTaken

ActionTaken(DD) Where the system returns a description of the action taken as a result of this function call.

VDHOpen Parameter - FileSize

FileSize(DD) The new file's logical size (EOD) in bytes.

VDHOpen Parameter - FileAttribute

FileAttribute(DD) File attribute bits used on file creation.

VDHOpen Parameter - OpenFLag

OpenFLag(DD) Specifies the action taken depending on whether the file exists.

Possible actions are:

VDHOPEN_FILE_EXISTED File existed
VDHOPEN_FILE_CREATED File created
VDHOPEN_FILE_TRUNCATED File replaced

VDHOpen Parameter - OpenMode

OpenMode(DD) Describes the mode of the Openfunction.

VDHOpen Parameter - EABuf

EABuf(DD) Address of a VDH_EAOP structure, or NULL.

VDHOpen Return Value - rc

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

Failure If the function fails, it returns 0 (zero). If the function fails, 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(DD) Pointer to the ASCIIZ string containing the name of the device or file to open.

FileHandle(DD) Where the system returns the file handle.

ActionTaken(DD) Where the system returns a description of the action taken as a result of this function call.

FileSize(DD) The new file's logical size (EOD) in bytes.

FileAttribute(DD) File attribute bits used on file creation.

OpenFLag(DD) Specifies the action taken depending on whether the file exists.

Possible actions are:

VDHOPEN_FILE_EXISTED File existed
VDHOPEN_FILE_CREATED File created
VDHOPEN_FILE_TRUNCATED File replaced

OpenMode(DD) Describes the mode of the Openfunction.

EABuf(DD) Address of a VDH_EAOP structure, or NULL.

VDHOpen - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: Any handles the virtual device driver opened for the terminating DOS session must be closed with VDHClose.

Notes: Using 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 . inc 

EXTERN    VDHOpenPDD : NEAR 
DeviceName       DD   ?      ;    Pointer   to   device   name   of   physical   device   driver   to   open 
VDDEntryPoint    DQ   ?      ;    VDD   entry   point   for   VDD / PDD   communication 

PUSH      DeviceName       ;    Push   DeviceName 
PUSH      VDDEntryPoint    ;    Push   VDDEntryPoint 

CALL      VDHOpenPDD        ;   Call   the   function

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

EXTERN    VDHOpenPDD : NEAR 
DeviceName       DD   ?      ;    Pointer   to   device   name   of   physical   device   driver   to   open 
VDDEntryPoint    DQ   ?      ;    VDD   entry   point   for   VDD / PDD   communication 

PUSH      DeviceName       ;    Push   DeviceName 
PUSH      VDDEntryPoint    ;    Push   VDDEntryPoint 

CALL      VDHOpenPDD        ;   Call   the   function

VDHOpenPDD Parameter - DeviceName

DeviceName(DD) Pointer to the device name of the physical device driver to open.

VDHOpenPDD Parameter - VDDEntryPoint

VDDEntryPoint(DQ) Virtual device driver entry point for use by the physical device driver. Since physical device drivers are 16:16 modules, this is a 16:32 entry point.

The interface for the VDDEntryPoint:

EntryPoint  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 12] - ulFunc (DD) - Function code
;                        All function codes are private to a PDD/VDD pair.
;           [ESP +  8] - ul1 (DD)    - Function-specific
;                     If a pointer, it is 16:16, and will generally
;                        be an input packet.
;           [ESP +  4] - ul2 (DD)    - Function-specific
;                   If a pointer, it is 16:16, and will generally
;                        be an output packet.
;    EXIT  SUCCESS  Returns a non-zero value in EAX
;          FAILURE  Returns 0 in EAX

VDHOpenPDD Return Value - rc

Success If the function is successful, it returns a pointer to the physical device driver Inter-Device-Driver Communication (IDC) function. See " 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(DD) Pointer to the device name of the physical device driver to open.

VDDEntryPoint(DQ) Virtual device driver entry point for use by the physical device driver. Since physical device drivers are 16:16 modules, this is a 16:32 entry point.

The interface for the VDDEntryPoint:

EntryPoint  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 12] - ulFunc (DD) - Function code
;                        All function codes are private to a PDD/VDD pair.
;           [ESP +  8] - ul1 (DD)    - Function-specific
;                     If a pointer, it is 16:16, and will generally
;                        be an input packet.
;           [ESP +  4] - ul2 (DD)    - Function-specific
;                   If a pointer, it is 16:16, and will generally
;                        be an output packet.
;    EXIT  SUCCESS  Returns a non-zero value in EAX
;          FAILURE  Returns 0 in EAX

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   VDHRequestVDD   to   enable   a   virtual   device   driver   to 
communicate   with   another   virtual   device   driver . 
The   name   must   be   one 
that   was   previously   registered   by   using   VDHRegisterVDD . 
* / 

include   mvdm . inc 

EXTERN    VDHOpenVDD : NEAR 
VDDName    DD   ?      ;    Pointer   to   the   name   of   the   virtual   device   driver   to   open 

PUSH      VDDName    ;    Push   VDDName 

CALL      VDHOpenVDD ;   Call   the   function

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

include   mvdm . inc 

EXTERN    VDHOpenVDD : NEAR 
VDDName    DD   ?      ;    Pointer   to   the   name   of   the   virtual   device   driver   to   open 

PUSH      VDDName    ;    Push   VDDName 

CALL      VDHOpenVDD ;   Call   the   function

VDHOpenVDD Parameter - VDDName

VDDName(DD) Pointer to a string containing the name of the virtual device driver to open.

VDHOpenVDD Return Value - rc

Success If the function is successful, it returns a handle to the virtual device driver.

Failure If the function fails, it returns 0 (zero). This can occur if:

The virtual device driver referenced by 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(DD) Pointer to a string containing the name of the virtual device driver to open.

VDHOpenVDD - Purpose

Context Issues: This function can be called only in the DOS session-task context, typically during DOS session creation.

DOS Session Terminations: The virtual device driver must communicate with the opened virtual device driver to ensure that any resources for the terminating DOS session are freed. In addition, the virtual device driver must communicate with any virtual device driver or OS/2 clients to ensure that any resources created due to the connection are freed. Notes: The recommended way for two virtual device drivers to rendezvous with this function is for each to attempt to open the other at the first creation of a DOS session. This allows the two virtual device drivers to work together regardless of the order in which they are initialized.

VDHOpenVDD - Topics

Select an item:

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

EXTERN    VDHOpenVIRQ : NEAR 
IRQNumber      DD   ?      ;    Number   of   the   IRQ   to   open 
EOIHandler     DD   ?      ;    Address   of   End - Of - Interrupt   ( EOI )   handler 
IRETHandler    DD   ?      ;    Address   of   Interrupt   Return   ( IRET )   handler 
Timeout        DD   ?      ;    IRET   timeout   value   in   milliseconds 
OptionFlag     DD   ?      ;    Indicates   whether   the   IRQ   can   be   shared 

PUSH      IRQNumber      ;    Push   IRQNumber 
PUSH      EOIHandler     ;    Push   EOIHandler 
PUSH      IRETHandler    ;    Push   IRETHandler 
PUSH      Timeout        ;    Push   Timeout 
PUSH      OptionFlag     ;    Push   OptionFlag 

CALL      VDHOpenVIRQ      ;   Call   the   function

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

EXTERN    VDHOpenVIRQ : NEAR 
IRQNumber      DD   ?      ;    Number   of   the   IRQ   to   open 
EOIHandler     DD   ?      ;    Address   of   End - Of - Interrupt   ( EOI )   handler 
IRETHandler    DD   ?      ;    Address   of   Interrupt   Return   ( IRET )   handler 
Timeout        DD   ?      ;    IRET   timeout   value   in   milliseconds 
OptionFlag     DD   ?      ;    Indicates   whether   the   IRQ   can   be   shared 

PUSH      IRQNumber      ;    Push   IRQNumber 
PUSH      EOIHandler     ;    Push   EOIHandler 
PUSH      IRETHandler    ;    Push   IRETHandler 
PUSH      Timeout        ;    Push   Timeout 
PUSH      OptionFlag     ;    Push   OptionFlag 

CALL      VDHOpenVIRQ      ;   Call   the   function

VDHOpenVIRQ Parameter - IRQNumber

IRQNumber(DD) Number of the IRQ to open.

VDHOpenVIRQ Parameter - EOIHandler

EOIHandler(DD) Address of End-Of-Interrupt (EOI) handler.

Linear address of the handler to be called when EOI is received by VPIC from a DOS session for the IRQ. If this is not desired, put a 0 (zero) in this parameter. Note that the IRQ is no longer "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:

EOIHdlr  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

VDHOpenVIRQ Parameter - IRETHandler

IRETHandler(DD) Address of Interrupt Return (IRET) handler.

Linear address of the handler to be called when the IRET in the DOS session 's interrupt code is executed for this IRQ. If this is not desired, set the parameter to 0 (zero). The interface for the IRET routine is:

IRETHdlr  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

VDHOpenVIRQ Parameter - Timeout

Timeout(DD) IRET timeout value in milliseconds. When the timeout expires, the virtual device driver's IRET handler is called as if the IRET had occurred. A value of -1 indicates that no timeout occurs.

VDHOpenVIRQ Parameter - OptionFlag

OptionFlag(DD) Option flag. Indicates whether the IRQ can be shared.

Possible value:

VPIC_SHARE_IRQ Indicates that the virtual device driver is willing to share the IRQ with another virtual device driver. All virtual device drivers that virtualize the same IRQ must pass this flag. Whether a particular IRQ is shared or unshared is determined by the setting of OptionFlagby the first virtual device driver to open the IRQ.

VDHOpenVIRQ Return Value - rc

Success If the function is successful, it returns an IRQ handle.

Failure If the function fails, it returns 0 (zero). VDHGetErrorshould be called to determine the nature of the problem. If IRQNumber, EOIHandler, IRETHandler, or OptionFlagare invalid, a system halt occurs.

VDHOpenVIRQ - Parameters

IRQNumber(DD) Number of the IRQ to open.

EOIHandler(DD) Address of End-Of-Interrupt (EOI) handler.

Linear address of the handler to be called when EOI is received by VPIC from a DOS session for the IRQ. If this is not desired, put a 0 (zero) in this parameter. Note that the IRQ is no longer "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:

EOIHdlr  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

IRETHandler(DD) Address of Interrupt Return (IRET) handler.

Linear address of the handler to be called when the IRET in the DOS session 's interrupt code is executed for this IRQ. If this is not desired, set the parameter to 0 (zero). The interface for the IRET routine is:

IRETHdlr  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 4] - pcrf - Pointer to client register frame
;    EXIT   None
;
; USES      EAX, ECX, EDX, FS, GS, Flags
; CONTEXT   DOS session-task

Timeout(DD) IRET timeout value in milliseconds. When the timeout expires, the virtual device driver's IRET handler is called as if the IRET had occurred. A value of -1 indicates that no timeout occurs.

OptionFlag(DD) Option flag. Indicates whether the IRQ can be shared.

Possible value:

VPIC_SHARE_IRQ Indicates that the virtual device driver is willing to share the IRQ with another virtual device driver. All virtual device drivers that virtualize the same IRQ must pass this flag. Whether a particular IRQ is shared or unshared is determined by the setting of OptionFlagby the first virtual device driver to open the IRQ.

VDHOpenVIRQ - Purpose

Context Issues: This function can be called only in the initialization context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: A maximum of 32 virtual device drivers can share an IRQ.

VDHOpenVIRQ - Topics

Select an item:

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

EXTERN    VDHPhysicalDisk : NEAR 
Function    DD   ?      ;    Type   of   partitionable   disks '   information 
DataPtr     DD   ?      ;    Pointer   to   the   return   buffer 
DataLen     DD   ?      ;    Length   of   the   return   buffer 
ParmPtr     DD   ?      ;    Pointer   to   the   user - supplied   information 
ParmLen     DD   ?      ;    Length   of   the   user - supplied   information 

PUSH      Function    ;    Push   Function 
PUSH      DataPtr     ;    Push   DataPtr 
PUSH      DataLen     ;    Push   DataLen 
PUSH      ParmPtr     ;    Push   ParmPtr 
PUSH      ParmLen     ;    Push   ParmLen 

CALL      VDHPhysicalDisk   ;   Call   the   function

VDHPhysicalDisk - Format

/*

This   function   returns   information   about   partitionable   disks . 
* / 

include   mvdm . inc 

EXTERN    VDHPhysicalDisk : NEAR 
Function    DD   ?      ;    Type   of   partitionable   disks '   information 
DataPtr     DD   ?      ;    Pointer   to   the   return   buffer 
DataLen     DD   ?      ;    Length   of   the   return   buffer 
ParmPtr     DD   ?      ;    Pointer   to   the   user - supplied   information 
ParmLen     DD   ?      ;    Length   of   the   user - supplied   information 

PUSH      Function    ;    Push   Function 
PUSH      DataPtr     ;    Push   DataPtr 
PUSH      DataLen     ;    Push   DataLen 
PUSH      ParmPtr     ;    Push   ParmPtr 
PUSH      ParmLen     ;    Push   ParmLen 

CALL      VDHPhysicalDisk   ;   Call   the   function

VDHPhysicalDisk Parameter - Function

Function(DD) Type of partitionable disks' information to obtain.

Possible values are:

VDHPHYD_GET_DISKS Obtain the total number of partitionable disks
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(DD) Pointer to the return buffer.

VDHPhysicalDisk Parameter - DataLen

DataLen(DD) Length of the return buffer.

The returned data for each function is described as follows (all lengths are in bytes):

VDHPHYD_GET_DISKS Data Length=2. Total number of partitionable disks in the system. 1-based.

VDHPHYD_GET_HANDLE Data Length=2. Handle for the specified partitionable disk for Category 9 IOCtls.

VDHPHYD_RELEASE_HANDLE Data Length=0. None; pointer must be 0 (zero).

VDHPhysicalDisk Parameter - ParmPtr

ParmPtr(DD) Pointer to the user-supplied information.

VDHPhysicalDisk Parameter - ParmLen

ParmLen(DD) Length of the user-supplied information (all lengths are in bytes):

VDHPHYD_GET_DISKS Parm Length=0. None; must be set to 0 (zero). 1-based.

VDHPHYD_GET_HANDLE Parm Length=string length. ASCIIZ string that specifies the partitionable disk.

VDHPHYD_RELEASE_HANDLE Parm Length=2. Handle obtained from VDHPHYD_GET_ HANDLE.

VDHPhysicalDisk Return Value - rc

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

Failure If the function fails, it returns 0 (zero). 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(DD) 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(DD) Pointer to the return buffer.

DataLen(DD) Length of the return buffer.

The returned data for each function is described as follows (all lengths are in bytes):

VDHPHYD_GET_DISKS Data Length=2. Total number of partitionable disks in the system. 1-based.

VDHPHYD_GET_HANDLE Data Length=2. Handle for the specified partitionable disk for Category 9 IOCtls.

VDHPHYD_RELEASE_HANDLE Data Length=0. None; pointer must be 0 (zero).

ParmPtr(DD) Pointer to the user-supplied information.

ParmLen(DD) Length of the user-supplied information (all lengths are in bytes):

VDHPHYD_GET_DISKS Parm Length=0. None; must be set to 0 (zero). 1-based.

VDHPHYD_GET_HANDLE Parm Length=string length. ASCIIZ string that specifies the partitionable disk.

VDHPHYD_RELEASE_HANDLE Parm Length=2. Handle obtained from VDHPHYD_GET_ HANDLE.

VDHPhysicalDisk - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: The handle obtained with Function Value=2 is released with Function Value=3. The ASCIIZ string used to specify the partitionable disk must be of the following format:

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

EXTERN    VDHPopInt : NEAR 
     DD   ? 

PUSH           ;    Push 

CALL      VDHP ;   Call   the   function

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

EXTERN    VDHPopInt : NEAR 
     DD   ? 

PUSH           ;    Push 

CALL      VDHP ;   Call   the   function

VDHPopInt Parameter -

(DD) None.

VDHPopInt Return Value - rc

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

Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack overflow would occur. A stack exception will be simulated to the client.

VDHPopInt - Parameters

(DD) None.

VDHPopInt - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This function always returns Successful when the DOS session is in client mode because no data accesses below 1MB can cause a fault.

VDHPopInt - Topics

Select an item:

Format
Parameters 
Return Codes 
Purpose 
Glossary

VDHPopRegs

Select an item:

Format
Parameters 
Return Codes 
Purpose 
Glossary

/*

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

include   mvdm . inc 

EXTERN    VDHPopRegs : NEAR 
RegFlag    DD   ?      ;    Indicates   which   client   registers   to   pop 

PUSH      RegFlag    ;    Push   RegFlag 

CALL      VDHPopRegs ;   Call   the   function

VDHPopRegs - Format

/*

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

include   mvdm . inc 

EXTERN    VDHPopRegs : NEAR 
RegFlag    DD   ?      ;    Indicates   which   client   registers   to   pop 

PUSH      RegFlag    ;    Push   RegFlag 

CALL      VDHPopRegs ;   Call   the   function

VDHPopRegs Parameter - RegFlag

RegFlag(DD) 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

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(DD) 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 - 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 . inc 

EXTERN    VDHPopStack : NEAR 
NumBytes    DD   ?      ;    Number   of   bytes   to   pop   off   the   client ' s   stack 
DataPtr     DD   ?      ;    Pointer   to   data   to   pop   off   client ' s   stack 

PUSH      NumBytes    ;    Push   NumBytes 
PUSH      DataPtr     ;    Push   DataPtr 

CALL      VDHPopStack   ;   Call   the   function

VDHPopStack - Format

/*

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

include   mvdm . inc 

EXTERN    VDHPopStack : NEAR 
NumBytes    DD   ?      ;    Number   of   bytes   to   pop   off   the   client ' s   stack 
DataPtr     DD   ?      ;    Pointer   to   data   to   pop   off   client ' s   stack 

PUSH      NumBytes    ;    Push   NumBytes 
PUSH      DataPtr     ;    Push   DataPtr 

CALL      VDHPopStack   ;   Call   the   function

VDHPopStack Parameter - NumBytes

NumBytes(DD) Number of bytes to pop off the client's stack. Must be an even number.

VDHPopStack Parameter - DataPtr

DataPtr(DD) Pointer to the data to pop off the client's stack.

VDHPopStack Return Value - rc

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

Failure If this function fails, it returns 0 (zero) if a fault would occur when accessing the user stack. If NumBytesis odd, a system halt occurs.

VDHPopStack - Parameters

NumBytes(DD) Number of bytes to pop off the client's stack. Must be an even number.

DataPtr(DD) Pointer to the data to pop off the client's stack.

VDHPopStack - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This is a very low-level service. Appropriate care should be exercised in its use to ensure that the client's stack is not damaged. This service handles stack wraparound, and always returns successful when the DOS session is in V86-mode because no data accesses below 1MB can cause a fault.

VDHPopStack - Topics

Select an item:

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

EXTERN    VDHPopup : NEAR 
ParmTable      DD   ?      ;    Pointer   to   a   table   of   substitution   strings 
StrCount       DD   ?      ;    Number   of   substitution   strings 
MsgNumber      DD   ?      ;    Message   number 
RespPtr        DD   ?      ;    Pointer   to   a   DD   to   receive   the   response 
RespAllowed    DD   ?      ;    Bit   field   describing   the   allowed   responses 
Reserved       DD   ?      ;    Reserved ;   must   be   set   to   NULL 

PUSH      ParmTable      ;    Push   ParmTable 
PUSH      StrCount       ;    Push   StrCount 
PUSH      MsgNumber      ;    Push   MsgNumber 
PUSH      RespPtr        ;    Push   RespPtr 
PUSH      RespAllowed    ;    Push   RespAllowed 
PUSH      Reserved       ;    Push   Reserved 

CALL      VDHPopup      ;   Call   the   function

VDHPopup - Format

/*

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

include   mvdm . inc 

EXTERN    VDHPopup : NEAR 
ParmTable      DD   ?      ;    Pointer   to   a   table   of   substitution   strings 
StrCount       DD   ?      ;    Number   of   substitution   strings 
MsgNumber      DD   ?      ;    Message   number 
RespPtr        DD   ?      ;    Pointer   to   a   DD   to   receive   the   response 
RespAllowed    DD   ?      ;    Bit   field   describing   the   allowed   responses 
Reserved       DD   ?      ;    Reserved ;   must   be   set   to   NULL 

PUSH      ParmTable      ;    Push   ParmTable 
PUSH      StrCount       ;    Push   StrCount 
PUSH      MsgNumber      ;    Push   MsgNumber 
PUSH      RespPtr        ;    Push   RespPtr 
PUSH      RespAllowed    ;    Push   RespAllowed 
PUSH      Reserved       ;    Push   Reserved 

CALL      VDHPopup      ;   Call   the   function

VDHPopup Parameter - ParmTable

ParmTable(DD) Pointer to a table of substitution strings.

VDHPopup Parameter - StrCount

StrCount(DD) Number of substitution strings.

VDHPopup Parameter - MsgNumber

MsgNumber(DD) Message number.

VDHPopup Parameter - RespPtr

RespPtr(DD) Pointer to a DD to receive the returned response, filled on exit.

VDHPopup Parameter - RespAllowed

RespAllowed(DD) Bit field describing the allowed responses.

The allowed values are (any combination of these flags can be specified):

VDHP_FAIL (0001H)
VDHP_RETRY (0004H)
VDHP_IGNORE (0008H)
VDHP_TERMINATE_SESSION (0002H)

VDHPopup Parameter - Reserved

Reserved(DD) Reserved. Must be set to NULL.

VDHPopup Return Value - rc

Success If the function is successful, it returns a nonzero value and the variable pointed to by 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(DD) Pointer to a table of substitution strings.

StrCount(DD) Number of substitution strings.

MsgNumber(DD) Message number.

RespPtr(DD) Pointer to a DD to receive the returned response, filled on exit.

RespAllowed(DD) Bit field describing the allowed responses.

The allowed values are (any combination of these flags can be specified):

VDHP_FAIL (0001H)
VDHP_RETRY (0004H)
VDHP_IGNORE (0008H)
VDHP_TERMINATE_SESSION (0002H)

Reserved(DD) Reserved. Must be set to NULL.

VDHPopup - Purpose

Context Issues: This function can be called in the initialization context or the DOS session-task context. If it is called at initialization time, the message is displayed as a string on the console as if a 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 . inc 

EXTERN    VDHPostEventSem : NEAR 
EventSemHandle    DD   ?      ;    Handle   of   an   event   semaphore 

PUSH      EventSemHandle    ;    Push   EventSemHandle 

CALL      VDHPostEventSem         ;   Call   the   function

VDHPostEventSem - Format

/*

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

include   mvdm . inc 

EXTERN    VDHPostEventSem : NEAR 
EventSemHandle    DD   ?      ;    Handle   of   an   event   semaphore 

PUSH      EventSemHandle    ;    Push   EventSemHandle 

CALL      VDHPostEventSem         ;   Call   the   function

VDHPostEventSem Parameter - EventSemHandle

EventSemHandle(DD) Handle of the event semaphore to post.

VDHPostEventSem Return Value - rc

Success If the function is successful, it will return nothing.

Failure Posting a semaphore that is invalid or is already posted causes a system halt to occur.

VDHPostEventSem - Parameters

EventSemHandle(DD) Handle of the event semaphore to post.

VDHPostEventSem - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHPostEventSem - Topics

Select an item:

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

EXTERN    VDHPrintClose : NEAR 
VDMHandle    DD   ?      ;    DOS   session   handle 

PUSH      VDMHandle    ;    Push   VDMHandle 

CALL      VDHPrintClose    ;   Call   the   function

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

EXTERN    VDHPrintClose : NEAR 
VDMHandle    DD   ?      ;    DOS   session   handle 

PUSH      VDMHandle    ;    Push   VDMHandle 

CALL      VDHPrintClose    ;   Call   the   function

VDHPrintClose Parameter - VDMHandle

VDMHandle(DD) DOS session handle.

VDHPrintClose Return Value - rc

None.

VDHPrintClose - Parameters

VDMHandle(DD) DOS session handle.

VDHPrintClose - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: The system will flush and close any open printers when the DOS session is terminated.

Notes: If a printer has been left open because of direct access to the parallel ports, it will also be closed.

VDHPrintClose - Topics

Select an item:

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

EXTERN    VDHPushFarCall : NEAR 
SegOffAddr    DQ   ?      ;    Address   of   V86   mode   or   protected   mode   code   to   call 

PUSH      SegOffAddr    ;    Push   SegOffAddr 

CALL      VDHPushFarCall     ;   Call   the   function

VDHPushFarCall - Format

/*

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

include   mvdm . inc 

EXTERN    VDHPushFarCall : NEAR 
SegOffAddr    DQ   ?      ;    Address   of   V86   mode   or   protected   mode   code   to   call 

PUSH      SegOffAddr    ;    Push   SegOffAddr 

CALL      VDHPushFarCall     ;   Call   the   function

VDHPushFarCall Parameter - SegOffAddr

SegOffAddr(DQ) The V86-mode segment:offset address of the V86-mode code to call, or selector:offset of protected-mode code to call.

VDHPushFarCall Return Value - rc

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

Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception is simulated to the client.

VDHPushFarCall - Parameters

SegOffAddr(DQ) The V86-mode segment:offset address of the V86-mode code to call, or selector:offset of protected-mode code to call.

VDHPushFarCall - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This function does not take effect until the operating system returns to the DOS session. In most cases, 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   n   instruction . 
Any   virtual   device   driver   hooked   on   this   interrupt   with   VDHInstallIntHook 
will   get   control   as   expected . 
The   VDHArmReturnHook   service   can   be   used   after   this 
function   is   called   to 
regain   control   when   the   V86   code   executes   the   Interrupt   Return   ( IRET ) . 

If   the   DOS   session   is   in   V86 - mode ,   the   V86 - mode   handler   from   the   IVT   is 
called . 
If   the   DOS   session   is   in   protected   mode ,   the   protected - mode   interrupt 
handler   is   called . 
* / 

include   mvdm . inc 

EXTERN    VDHPushInt : NEAR 
Vector    DD   ?      ;    Number   of   the   interrupt   vector   to   push 

PUSH      Vector    ;    Push   Vector 

CALL      VDHPushIn ;   Call   the   function

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

include   mvdm . inc 

EXTERN    VDHPushInt : NEAR 
Vector    DD   ?      ;    Number   of   the   interrupt   vector   to   push 

PUSH      Vector    ;    Push   Vector 

CALL      VDHPushIn ;   Call   the   function

VDHPushInt Parameter - Vector

Vector(DD) Number of the interrupt vector to push (0-255).

VDHPushInt Return Value - rc

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

Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If Vectoris invalid, a system halt occurs.

VDHPushInt - Parameters

Vector(DD) Number of the interrupt vector to push (0-255).

VDHPushInt - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This function does not take effect until the operating system returns to V86 mode. This function always returns successful when the DOS session is in V86 mode because no data accesses below 1MB can cause a fault .

VDHPushInt - Topics

Select an item:

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

EXTERN    VDHPushRegs : NEAR 
RegFlag    DD   ?      ;    Flag   indicating   which   client   registers   to   push 

PUSH      RegFlag    ;    Push   RegFlag 

CALL      VDHPushRegs ;   Call   the   function

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

EXTERN    VDHPushRegs : NEAR 
RegFlag    DD   ?      ;    Flag   indicating   which   client   registers   to   push 

PUSH      RegFlag    ;    Push   RegFlag 

CALL      VDHPushRegs ;   Call   the   function

VDHPushRegs Parameter - RegFlag

RegFlag(DD) Flag indicating which client registers to push. These flags can be ORed together to indicate more than one register.

Possible values are:

VDHREG_AX Push the AX register
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

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(DD) Flag indicating which client registers to push. These flags can be ORed together to indicate more than one register.

Possible values are:

VDHREG_AX Push the AX register
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 - 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 . inc 

EXTERN    VDHPushStack : NEAR 
NumBytes    DD   ?      ;    Number   of   bytes   to   push   on   the   client ' s   stack 
DataPtr     DD   ?      ;    Pointer   to   the   data   to   push   on   the   stack 

PUSH      NumBytes    ;    Push   NumBytes 
PUSH      DataPtr     ;    Push   DataPtr 

CALL      VDHPushStack   ;   Call   the   function

VDHPushStack - Format

/*

This   function   pushes   data   onto   the   client ' s   stack . 
* / 

include   mvdm . inc 

EXTERN    VDHPushStack : NEAR 
NumBytes    DD   ?      ;    Number   of   bytes   to   push   on   the   client ' s   stack 
DataPtr     DD   ?      ;    Pointer   to   the   data   to   push   on   the   stack 

PUSH      NumBytes    ;    Push   NumBytes 
PUSH      DataPtr     ;    Push   DataPtr 

CALL      VDHPushStack   ;   Call   the   function

VDHPushStack Parameter - NumBytes

NumBytes(DD) Number of bytes to push onto the client's stack. Must be an even number.

VDHPushStack Parameter - DataPtr

DataPtr(DD) A pointer to the data to be pushed.

VDHPushStack Return Value - rc

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

Failure If the function fails, it returns 0 if the client is in protected mode and the stack is invalid or a stack underflow would occur. A stack exception will be simulated to the client. If NumBytes is odd, a system halt occurs.

VDHPushStack - Parameters

NumBytes(DD) Number of bytes to push onto the client's stack. Must be an even number.

DataPtr(DD) A pointer to the data to be pushed.

VDHPushStack - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This is a very low-level service. Appropriate care should be exercised in its use to ensure that the client's stack is not corrupted. This service handles stack wraparound, and always returns successful when the DOS session is in V86-mode because no data accesses below 1MB can cause a fault.

VDHPushStack - Topics

Select an item:

Format
Parameters 
Return Codes 
Purpose 
Glossary

VDHPutSysValue

Select an item:

Format
Parameters 
Return Codes 
Purpose 
Glossary

/*

This   function   sets   a   system   value . 
* / 

include   mvdm . inc 

EXTERN    VDHPutSysValue : NEAR 
Index    DD   ?      ;    Index   of   the   system   variable   to   set 
Value    DD   ?      ;    New   value   for   the   system   variable 

PUSH      Index    ;    Push   Index 
PUSH      Value    ;    Push   Value 

CALL      VDHPutSysVal ;   Call   the   function

VDHPutSysValue - Format

/*

This   function   sets   a   system   value . 
* / 

include   mvdm . inc 

EXTERN    VDHPutSysValue : NEAR 
Index    DD   ?      ;    Index   of   the   system   variable   to   set 
Value    DD   ?      ;    New   value   for   the   system   variable 

PUSH      Index    ;    Push   Index 
PUSH      Value    ;    Push   Value 

CALL      VDHPutSysVal ;   Call   the   function

VDHPutSysValue Parameter - Index

Index(DD) Index of the system value to set. System value indexes are defined in VDMM.INC and listed in VDHQuerySysValue.

VDHPutSysValue Parameter - Value

Value(DD) New value for the system variable.

VDHPutSysValue Return Value - rc

Success If the function was successful, it returns nothing.

Failure If Index is invalid, a system halt occurs.

VDHPutSysValue - Parameters

Index(DD) Index of the system value to set. System value indexes are defined in VDMM.INC and listed in VDHQuerySysValue.

Value(DD) New value for the system variable.

VDHPutSysValue - Purpose

Context Issues: This function can be called in the initialization or DOS session-task (DOS session creation) context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This service is intended for system virtual device drivers to export system constants, such as ROM memory size. The behavior of the system is undefined if this service is used for any other purpose.

VDHPutSysValue - Topics

Select an item:

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

EXTERN    VDHQueryFreePages : NEAR 
     DD   ? 

PUSH           ;    Push 

CALL      VDHQueryFree ;   Call   the   function

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

EXTERN    VDHQueryFreePages : NEAR 
     DD   ? 

PUSH           ;    Push 

CALL      VDHQueryFree ;   Call   the   function

VDHQueryFreePages Parameter -

(DD) None.

VDHQueryFreePages Return Value - rc

Success If the function is successful, it returns the number of bytes of free virtual memory.

Failure If the function fails, it returns nothing.

VDHQueryFreePages - Parameters

(DD) None.

VDHQueryFreePages - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This is a system-wide value that is not specific to the virtual address space of the DOS session.

VDHQueryFreePages - Topics

Select an item:

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

EXTERN    VDHQueryHookData : NEAR 
HookHandle    DD   ?      ;    Hook   handle   from   VDHAllocHook 

PUSH      HookHandle    ;    Push   HookHandle 

CALL      VDHQueryHookData     ;   Call   the   function

VDHQueryHookData - Format

/*

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

include   mvdm . inc 

EXTERN    VDHQueryHookData : NEAR 
HookHandle    DD   ?      ;    Hook   handle   from   VDHAllocHook 

PUSH      HookHandle    ;    Push   HookHandle 

CALL      VDHQueryHookData     ;   Call   the   function

VDHQueryHookData Parameter - HookHandle

HookHandle(DD) Hook handle (from VDHAllocHook) for the hook to query.

VDHQueryHookData Return Value - rc

Success If the function is successful, it returns a pointer to the reference data block.

Failure If HookHandle is invalid or if there is no reference data (that is, the RefDataSize parameter for VDHAllocHook is 0), a system halt occurs.

VDHQueryHookData - Parameters

HookHandle(DD) Hook handle (from VDHAllocHook) for the hook to query.

VDHQueryHookData - Purpose

Context Issues: This function can be called in the initialization, task, or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHQueryHookData - Topics

Select an item:

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

EXTERN    VDHQueryLin : NEAR 
Far16Addr    DD   ?      ;    16 : 16   addressto   be   converted 

PUSH      Far16Addr    ;    Push   Far16Addr 

CALL      VDHQueryLin    ;   Call   the   function

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

EXTERN    VDHQueryLin : NEAR 
Far16Addr    DD   ?      ;    16 : 16   addressto   be   converted 

PUSH      Far16Addr    ;    Push   Far16Addr 

CALL      VDHQueryLin    ;   Call   the   function

VDHQueryLin Parameter - Far16Addr

Far16Addr(DD) The 16:16 address to be converted to a 0:32 address.

VDHQueryLin Return Value - rc

Success If the function is successful, it returns the 0:32 address that corresponds to Far16Addr.

Failure If Far16Addr is an invalid selector, a system halt occurs.

VDHQueryLin - Parameters

Far16Addr(DD) The 16:16 address to be converted to a 0:32 address.

VDHQueryLin - Purpose

Context Issues: This function can be called in the initialization, task, or interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

Notes: This service does minimal checking on Far16Addr. The caller should make sure that Far16Addr is not invalid. If an invalid address is passed, this service can return an invalid address.

VDHQueryLin - Topics

Select an item:

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

EXTERN    VDHQueryKeyShift : NEAR 
VDMHandle    DD   ?      ;    DOS   session   handle 

PUSH      VDMHandle    ;    Push   VDMHandle 

CALL      VDHQueryKeyShift    ;   Call   the   function

VDHQueryKeyShift - Format

/*

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

include   mvdm . inc 

EXTERN    VDHQueryKeyShift : NEAR 
VDMHandle    DD   ?      ;    DOS   session   handle 

PUSH      VDMHandle    ;    Push   VDMHandle 

CALL      VDHQueryKeyShift    ;   Call   the   function

VDHQueryKeyShift Parameter - VDMHandle

VDMHandle(DD) DOS session handle.

VDHQueryKeyShift Return Value - rc

Returns a USHORT which is a bitmask that indicates the current key state:

Right Shift 1
Left Shift 2
Ctrl 4
ALT 8
Left Ctrl 100
Left ALT 200
Right Ctrl 400
Right ALT 800

VDHQueryKeyShift - Parameters

VDMHandle(DD) DOS session handle.

VDHQueryKeyShift - Purpose

Context Issues: This function can be called only in the interrupt context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHQueryKeyShift - Topics

Select an item:

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

EXTERN    VDHQueryProperty : NEAR 
PropertyName    DD   ?      ;    Pointer   to   a   property   name 

PUSH      PropertyName    ;    Push   PropertyName 

CALL      VDHQueryProperty       ;   Call   the   function

VDHQueryProperty - Format

/*

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

* / 

include   mvdm . inc 

EXTERN    VDHQueryProperty : NEAR 
PropertyName    DD   ?      ;    Pointer   to   a   property   name 

PUSH      PropertyName    ;    Push   PropertyName 

CALL      VDHQueryProperty       ;   Call   the   function

VDHQueryProperty Parameter - PropertyName

PropertyName(DD) Pointer to an ASCIIZ string containing the property name for which information is being sought. Maximum length is 40 characters, including the terminating NULL.

VDHQueryProperty Return Value - rc

Success The format of the return value for successful depends on the type of the property being queried:

VDMP_BOOL The return value is a BOOL (Boolean). A 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(DD) Pointer to an ASCIIZ string containing the property name for which information is being sought. Maximum length is 40 characters, including the terminating NULL.

VDHQueryProperty - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: All memory allocated by a virtual device driver for use by the terminating DOS session is freed by using VDHFreeMem.

Notes: A virtual device driver can assume that the property value is valid. The system validates all types, except VDMP_STRING and VDMP_MLSTR, by using the validation values passed on the call to VDHRegisterProperty. The string types are validated by calling the virtual device driver function registered through VDHRegisterProperty.

VDHQueryProperty - Topics

Select an item:

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

EXTERN    VDHQuerySel : NEAR 
VirtAddress    DD   ?      ;    0 : 32   virtual   address 

PUSH      VirtAddress    ;    Push   VirtAddress 

CALL      VDHQuerySel      ;   Call   the   function

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

EXTERN    VDHQuerySel : NEAR 
VirtAddress    DD   ?      ;    0 : 32   virtual   address 

PUSH      VirtAddress    ;    Push   VirtAddress 

CALL      VDHQuerySel      ;   Call   the   function

VDHQuerySel Parameter - VirtAddress

VirtAddress(DD) A 0:32 virtual address.

VDHQuerySel Return Value - rc

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

Failure If the specified linear address is not in a virtual device driver data object, a system halt occurs.

VDHQuerySel - Parameters

VirtAddress(DD) A 0:32 virtual address.

VDHQuerySel - Purpose

Context Issues: This function can be called in the initialization and task context:

During initialization time; query is allowed only on initialization and global data.
*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 . inc 

EXTERN    VDHQuerySem : NEAR 
SemHandle      DD   ?      ;    Handle   to   an   event   or   mutex   semaphore 
SemStatePtr    DD   ?      ;    Pointer   to   a   VDHSEMSTATE   data   area 

PUSH      SemHandle      ;    Push   SemHandle 
PUSH      SemStatePtr    ;    Push   SemStatePtr 

CALL      VDHQuerySem      ;   Call   the   function

VDHQuerySem - Format

/*

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

include   mvdm . inc 

EXTERN    VDHQuerySem : NEAR 
SemHandle      DD   ?      ;    Handle   to   an   event   or   mutex   semaphore 
SemStatePtr    DD   ?      ;    Pointer   to   a   VDHSEMSTATE   data   area 

PUSH      SemHandle      ;    Push   SemHandle 
PUSH      SemStatePtr    ;    Push   SemStatePtr 

CALL      VDHQuerySem      ;   Call   the   function

VDHQuerySem Parameter - SemHandle

SemHandle(DD) Semaphore handle.

VDHQuerySem Parameter - SemStatePtr

SemStatePtr(DD) A pointer to the data area to be filled with the state of the semaphore.

SemStatePtr points to a variable defined in VDMM.INC and structured as follows:

VDHSemState_s STRUC
        vss_SemType    DB   ?   ; VDH_EVENTSEM/VDH_MUTEXSEM
        vss_fOwned     DB   ?   ; 0 = Not Owned; 1 = Owned
        vss_fWaiter    DW   ?   ; 0 = No one waiting; 1 = Waiting
        vss_cRequest   DW   ?   ; Request count in mutex case
        vss_tid        DW   ?   ; TID of the owner, if owned
VDHSemState_s ENDS

VDHQuerySem Return Value -

None.

VDHQuerySem - Parameters

SemHandle(DD) Semaphore handle.

SemStatePtr(DD) A pointer to the data area to be filled with the state of the semaphore.

SemStatePtr points to a variable defined in VDMM.INC and structured as follows:

VDHSemState_s STRUC
        vss_SemType    DB   ?   ; VDH_EVENTSEM/VDH_MUTEXSEM
        vss_fOwned     DB   ?   ; 0 = Not Owned; 1 = Owned
        vss_fWaiter    DW   ?   ; 0 = No one waiting; 1 = Waiting
        vss_cRequest   DW   ?   ; Request count in mutex case
        vss_tid        DW   ?   ; TID of the owner, if owned
VDHSemState_s ENDS

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

EXTERN    VDHQuerySysValue : NEAR 
VDMHandle    DD   ?      ;    Index   of   the   system   variable   handle   of   the   DOS   session 
Index        DD   ?      ;    Index   values 

PUSH      VDMHandle    ;    Push   VDMHandle 
PUSH      Index        ;    Push   Index 

CALL      VDHQuerySysValue    ;   Call   the   function

VDHQuerySysValue - Format

/*

This   function   queries   a   system   value . 
* / 

include   mvdm . inc 

EXTERN    VDHQuerySysValue : NEAR 
VDMHandle    DD   ?      ;    Index   of   the   system   variable   handle   of   the   DOS   session 
Index        DD   ?      ;    Index   values 

PUSH      VDMHandle    ;    Push   VDMHandle 
PUSH      Index        ;    Push   Index 

CALL      VDHQuerySysValue    ;   Call   the   function

VDHQuerySysValue Parameter - VDMHandle

VDMHandle(DD) Index of the system variable handle of the DOS session to query. A value of 0 (zero) indicates the current DOS session.

VDHQuerySysValue Parameter - Index

Index(DD) VDHQuerySysValueindex values (as defined in VDMM.INC) and descriptions:

Global Values        Ordinal  Type   Units         Range
_____________        _______  ____   _____         _____

VDHGSV_DAY              0     DD     days          1 < = x < = 31
VDHGSV_MONTH            1     DD     months        1 < = x < = 12
VDHGSV_YEAR             2     DD     years         1980 < = x < = MAXULONG
VDHGSV_DAYOFWEEK        3     DD     days          0 < = x < = 6
VDHGSV_HOUR             4     DD     hours         0 < = x < = 24
VDHGSV_MINUTE           5     DD     minutes       0 < = x < = 60
VDHGSV_SECOND           6     DD     seconds       0 < = x < = 60
VDHGSV_HUNDREDTH        7     DD     1/100S        0 < = x < = 100
VDHGSV_SECONDS1970      8     DD     seconds       0 < = x < = MAXULONG
VDHGSV_TIMEZONE         9     DD     minutes       0 < = x < = MAXULONG
VDHGSV_MSECSBOOT        10    DD     milliseconds  0 < = x < = MAXULONG
VDHGSV_TIMERINTERVAL    11    DD     milliseconds  0 < = x < = 1000
VDHGSV_DYNVARIATION     12    DD                   TRUE(nonzero)/FALSE(0)
VDHGSV_MAXWAIT          13    DD     seconds       0 < = x < = MAXULONG
VDHGSV_MINTIMESLICE     14    DD     milliseconds  0 < = x < = MAXULONG
VDHGSV_MAXTIMESLICE     15    DD     milliseconds  0 < = x < = MAXULONG

Global Values        Ordinal  Type   Units         Range
_____________        _______  ____   _____         _____

VDHGSV_YIELD            16    DD                   TRUE(nonzero)/FALSE(0)
VDHGSV_TCYIELD          17    DD                   TRUE(nonzero)/FALSE(0)
VDHGSV_VERMAJOR         18    DD                   0 < = x < = MAXULONG
VDHGSV_VERMINOR         19    DD                   0 < = x < = MAXULONG
VDHGSV_VERREVISION      20    DD                   0 < = x < = 255
VDHGSV_MACHINETYPE      21    DD                   MACHINE_TYPE_
VDHGSV_BLACKHOLEADDR    22    DD     bytes         0 < = x < = MAXULONG
VDHGSV_BLACKHOLESIZE    23    DD     bytes         0 < = x < = MAXULONG
VDHGSV_FGNDSESSIONID    24    DD                   0 < = x < = MAXSESSIONS
VDHGSV_ARPLADDR         29    DD
VDHGSV_MACHINEINFO      30    DD                   Pointer to System
                                                   Configuration table
VDHGSV_PPOSREGS         31    DD                   Pointer to POS Regs
                                                   structure
VDHGSV_PICMASK          32    DD                   Original PIC mask values


Local Values         Ordinal  Type   Units         Range
____________         _______  ____   _____         _____

VDHLSV_HVDM           4096    DD
VDHLSV_PID            4097    DD
VDHLSV_PCRF           4098    DD
VDHLSV_SESSIONID      4099    DD                   N < = x < MAXSESSIONS
VDHLSV_FOREGROUND     4100    DD                   TRUE(nonzero)/FALSE(0)
VDHLSV_RMSIZE         4101    DD     KB            0 < x < = 640
VDHLSV_CODEPAGEID     4102    DD                   See DosGetCP
VDHLSV_PRIORITYCLASS  4103    DD                   See VDHSetPriority
VDHLSV_PRIORITYLEVEL  4104    DD                   See VDHSetPriority
VDHLSV_VPICBASE       4105    DD

VDHQuerySysValue Return Value - rc

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(DD) Index of the system variable handle of the DOS session to query. A value of 0 (zero) indicates the current DOS session.

Index(DD) VDHQuerySysValueindex values (as defined in VDMM.INC) and descriptions:

Global Values        Ordinal  Type   Units         Range
_____________        _______  ____   _____         _____

VDHGSV_DAY              0     DD     days          1 < = x < = 31
VDHGSV_MONTH            1     DD     months        1 < = x < = 12
VDHGSV_YEAR             2     DD     years         1980 < = x < = MAXULONG
VDHGSV_DAYOFWEEK        3     DD     days          0 < = x < = 6
VDHGSV_HOUR             4     DD     hours         0 < = x < = 24
VDHGSV_MINUTE           5     DD     minutes       0 < = x < = 60
VDHGSV_SECOND           6     DD     seconds       0 < = x < = 60
VDHGSV_HUNDREDTH        7     DD     1/100S        0 < = x < = 100
VDHGSV_SECONDS1970      8     DD     seconds       0 < = x < = MAXULONG
VDHGSV_TIMEZONE         9     DD     minutes       0 < = x < = MAXULONG
VDHGSV_MSECSBOOT        10    DD     milliseconds  0 < = x < = MAXULONG
VDHGSV_TIMERINTERVAL    11    DD     milliseconds  0 < = x < = 1000
VDHGSV_DYNVARIATION     12    DD                   TRUE(nonzero)/FALSE(0)
VDHGSV_MAXWAIT          13    DD     seconds       0 < = x < = MAXULONG
VDHGSV_MINTIMESLICE     14    DD     milliseconds  0 < = x < = MAXULONG
VDHGSV_MAXTIMESLICE     15    DD     milliseconds  0 < = x < = MAXULONG

Global Values        Ordinal  Type   Units         Range
_____________        _______  ____   _____         _____

VDHGSV_YIELD            16    DD                   TRUE(nonzero)/FALSE(0)
VDHGSV_TCYIELD          17    DD                   TRUE(nonzero)/FALSE(0)
VDHGSV_VERMAJOR         18    DD                   0 < = x < = MAXULONG
VDHGSV_VERMINOR         19    DD                   0 < = x < = MAXULONG
VDHGSV_VERREVISION      20    DD                   0 < = x < = 255
VDHGSV_MACHINETYPE      21    DD                   MACHINE_TYPE_
VDHGSV_BLACKHOLEADDR    22    DD     bytes         0 < = x < = MAXULONG
VDHGSV_BLACKHOLESIZE    23    DD     bytes         0 < = x < = MAXULONG
VDHGSV_FGNDSESSIONID    24    DD                   0 < = x < = MAXSESSIONS
VDHGSV_ARPLADDR         29    DD
VDHGSV_MACHINEINFO      30    DD                   Pointer to System
                                                   Configuration table
VDHGSV_PPOSREGS         31    DD                   Pointer to POS Regs
                                                   structure
VDHGSV_PICMASK          32    DD                   Original PIC mask values


Local Values         Ordinal  Type   Units         Range
____________         _______  ____   _____         _____

VDHLSV_HVDM           4096    DD
VDHLSV_PID            4097    DD
VDHLSV_PCRF           4098    DD
VDHLSV_SESSIONID      4099    DD                   N < = x < MAXSESSIONS
VDHLSV_FOREGROUND     4100    DD                   TRUE(nonzero)/FALSE(0)
VDHLSV_RMSIZE         4101    DD     KB            0 < x < = 640
VDHLSV_CODEPAGEID     4102    DD                   See DosGetCP
VDHLSV_PRIORITYCLASS  4103    DD                   See VDHSetPriority
VDHLSV_PRIORITYLEVEL  4104    DD                   See VDHSetPriority
VDHLSV_VPICBASE       4105    DD

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

EXTERN    VDHQueryVIRQ : NEAR 
VDMHandle    DD   ?      ;    IRQ   handle   from   DOS   session   handle 
IRQHandle    DD   ?      ;    IRQ   handle   from   VDHOpenVIRQ 

PUSH      VDMHandle    ;    Push   VDMHandle 
PUSH      IRQHandle    ;    Push   IRQHandle 

CALL      VDHQueryVIRQ    ;   Call   the   function

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

EXTERN    VDHQueryVIRQ : NEAR 
VDMHandle    DD   ?      ;    IRQ   handle   from   DOS   session   handle 
IRQHandle    DD   ?      ;    IRQ   handle   from   VDHOpenVIRQ 

PUSH      VDMHandle    ;    Push   VDMHandle 
PUSH      IRQHandle    ;    Push   IRQHandle 

CALL      VDHQueryVIRQ    ;   Call   the   function

VDHQueryVIRQ Parameter - VDMHandle

VDMHandle(DD) IRQ handle from VDHOpenVIRQDOS session handle. A value of 0 (zero) indicates the current DOS session.

VDHQueryVIRQ Parameter - IRQHandle

IRQHandle(DD) IRQ handle from VDHOpenVIRQ.

VDHQueryVIRQ Return Value - rc

Success If the function is successful, it returns the IRQ status as a DD of flag bits:

VPICQ_REQUEST_PENDING Request is pending for the queried IRQ
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(DD) IRQ handle from VDHOpenVIRQDOS session handle. A value of 0 (zero) indicates the current DOS session.

IRQHandle(DD) IRQ handle from VDHOpenVIRQ.

VDHQueryVIRQ - Purpose

Context Issues: This function can be called only in the task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHQueryVIRQ - Topics

Select an item:

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

EXTERN    VDHRaiseException : NEAR 
Exception    DD   ?      ;    An   exception   number 
ErrorCode    DD   ?      ;    Error   code   for   the   exception 
ExtraCode    DD   ?      ;    Extra   error   code 

PUSH      Exception    ;    Push   Exception 
PUSH      ErrorCode    ;    Push   ErrorCode 
PUSH      ExtraCode    ;    Push   ExtraCode 

CALL      VDHRaiseException    ;   Call   the   function

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

EXTERN    VDHRaiseException : NEAR 
Exception    DD   ?      ;    An   exception   number 
ErrorCode    DD   ?      ;    Error   code   for   the   exception 
ExtraCode    DD   ?      ;    Extra   error   code 

PUSH      Exception    ;    Push   Exception 
PUSH      ErrorCode    ;    Push   ErrorCode 
PUSH      ExtraCode    ;    Push   ExtraCode 

CALL      VDHRaiseException    ;   Call   the   function

VDHRaiseException Parameter - Exception

Exception(DD) An exception number that might be caused by the 80386 microprocessor.

VDHRaiseException Parameter - ErrorCode

ErrorCode(DD) Error code for the exception defined for the 80386 microprocessor.

VDHRaiseException Parameter - ExtraCode

ExtraCode(DD) Extra error code for DPMI 1.0 page faults.

VDHRaiseException Return Value - rc

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

Failure If the function fails, it returns 0 (zero).

VDHRaiseException - Parameters

Exception(DD) An exception number that might be caused by the 80386 microprocessor.

ErrorCode(DD) Error code for the exception defined for the 80386 microprocessor.

ExtraCode(DD) Extra error code for DPMI 1.0 page faults.

VDHRaiseException - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHRaiseException - Topics

Select an item:

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

EXTERN    VDHRead : NEAR 
FileHandle       DW   ?      ;    Handle   to   the   file   or   device   to   read 
ReadBufferPtr    DD   ?      ;    Address   of   the   buffer   to   store   the   bytes   read 
NumBytes         DD   ?      ;    Number   of   bytes   to   read 

PUSH      FileHandle       ;    Push   FileHandle 
PUSH      ReadBufferPtr    ;    Push   ReadBufferPtr 
PUSH      NumBytes         ;    Push   NumBytes 

CALL      VDHRead        ;   Call   the   function

VDHRead - Format

/*

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

include   mvdm . inc 

EXTERN    VDHRead : NEAR 
FileHandle       DW   ?      ;    Handle   to   the   file   or   device   to   read 
ReadBufferPtr    DD   ?      ;    Address   of   the   buffer   to   store   the   bytes   read 
NumBytes         DD   ?      ;    Number   of   bytes   to   read 

PUSH      FileHandle       ;    Push   FileHandle 
PUSH      ReadBufferPtr    ;    Push   ReadBufferPtr 
PUSH      NumBytes         ;    Push   NumBytes 

CALL      VDHRead        ;   Call   the   function

VDHRead Parameter - FileHandle

FileHandle(DW) Handle to the file or device to read.

VDHRead Parameter - ReadBufferPtr

ReadBufferPtr(DD) Address of the buffer to store the bytes read.

VDHRead Parameter - NumBytes

NumBytes(DD) Number of bytes to read.

VDHRead Return Value - rc

Success If the function is successful, it returns a count of the number of bytes read; this can be equal to 0 (zero).

Failure If the function fails, it returns 0FFFFFFFFH. 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(DW) Handle to the file or device to read.

ReadBufferPtr(DD) Address of the buffer to store the bytes read.

NumBytes(DD) Number of bytes to read.

VDHRead - Purpose

Context Issues: This function can be called only in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function.

VDHRead - Topics

Select an item:

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

EXTERN    VDHReadUBuf : NEAR 
DestBuffer       DD   ?      ;    Destination   buffer   for   copy . 
ByteCount        DD   ?      ;    Count   of   bytes 
Selector         DW   ?      ;    Application   selector 
OffsetPointer    DD   ?      ;    Address   of   the   variable   containing   the   offset 
Flag              DD   ?      ;    Checking   controls   flag 

PUSH      DestBuffer       ;    Push   DestBuffer 
PUSH      ByteCount        ;    Push   ByteCount 
PUSH      Selector         ;    Push   Selector 
PUSH      OffsetPointer    ;    Push   OffsetPointer 
PUSH      Flag              ;    Push   Flag 

CALL      VDHReadUBuf        ;   Call   the   function

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

EXTERN    VDHReadUBuf : NEAR 
DestBuffer       DD   ?      ;    Destination   buffer   for   copy . 
ByteCount        DD   ?      ;    Count   of   bytes 
Selector         DW   ?      ;    Application   selector 
OffsetPointer    DD   ?      ;    Address   of   the   variable   containing   the   offset 
Flag              DD   ?      ;    Checking   controls   flag 

PUSH      DestBuffer       ;    Push   DestBuffer 
PUSH      ByteCount        ;    Push   ByteCount 
PUSH      Selector         ;    Push   Selector 
PUSH      OffsetPointer    ;    Push   OffsetPointer 
PUSH      Flag              ;    Push   Flag 

CALL      VDHReadUBuf        ;   Call   the   function

VDHReadUBuf Parameter - DestBuffer

DestBuffer(DD) Destination buffer for copy.

VDHReadUBuf Parameter - ByteCount

ByteCount(DD) Count of bytes.

VDHReadUBuf Parameter - Selector

Selector(DW) Application selector.

VDHReadUBuf Parameter - OffsetPointer

OffsetPointer(DD) Address of the variable containing the offset for the start of the read.

VDHReadUBuf Parameter - Flag

Flag(DD) Flag containing checking controls.

Possible values are:

VPM_PROT_READ Check for read.
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

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(DD) Destination buffer for copy.

ByteCount(DD) Count of bytes.

Selector(DW) Application selector.

OffsetPointer(DD) Address of the variable containing the offset for the start of the read.

Flag(DD) Flag containing checking controls.

Possible values are:

VPM_PROT_READ Check for read.
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 - 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 . inc 

EXTERN    VDHReallocPages : NEAR 
ObjectAddress    DD   ?      ;    Address   of   the   memory   object   to   resize 
NumPages         DD   ?      ;    New   size   of   the   memory   object   ( in   4KB   pages ) 
Reserved         DD   ?      ;    Must   be   zero 

PUSH      ObjectAddress    ;    Push   ObjectAddress 
PUSH      NumPages         ;    Push   NumPages 
PUSH      Reserved         ;    Push   Reserved 

CALL      VDHReallocPages        ;   Call   the   function

VDHReallocPages - Format

/*

This   function   expands   or   shrinks   a   memory   object . 
* / 

include   mvdm . inc 

EXTERN    VDHReallocPages : NEAR 
ObjectAddress    DD   ?      ;    Address   of   the   memory   object   to   resize 
NumPages         DD   ?      ;    New   size   of   the   memory   object   ( in   4KB   pages ) 
Reserved         DD   ?      ;    Must   be   zero 

PUSH      ObjectAddress    ;    Push   ObjectAddress 
PUSH      NumPages         ;    Push   NumPages 
PUSH      Reserved         ;    Push   Reserved 

CALL      VDHReallocPages        ;   Call   the   function

VDHReallocPages Parameter - ObjectAddress

ObjectAddress(DD) Address of the memory object to reallocate or resize.

VDHReallocPages Parameter - NumPages

NumPages(DD) The new size of the memory object (in 4KB pages).

VDHReallocPages Parameter - Reserved

Reserved(DD) Must be set to zero.

VDHReallocPages Return Value - rc

Success If the function is successful, it returns that address of the reallocated memory block.

Failure If the function fails, it returns 0 (zero). 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(DD) Address of the memory object to reallocate or resize.

NumPages(DD) The new size of the memory object (in 4KB pages).

Reserved(DD) Must be set to zero.

VDHReallocPages - Purpose

Context Issues: This function can be called in the initialization or task context.

DOS Session Terminations: Any allocations that are not in the terminating DOS session's private area must be released by using VDHFreePages.

Notes: When an allocation made with 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 . inc 

EXTERN    VDHRegisterAPI : NEAR 
VDDName       DD   ?      ;    Pointer   to   the   name   of   the   virtual   device   driver 
pfnV86Hook    DD   ?      ;    V86 - mode   hook   routine   address 
pfnVPMHook    DD   ?      ;    VPM - mode   hook   routine   address 

PUSH      VDDName       ;    Push   VDDName 
PUSH      pfnV86Hook    ;    Push   pfnV86Hook 
PUSH      pfnVPMHook    ;    Push   pfnVPMHook 

CALL      VDHRegisterAPI     ;   Call   the   function

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

EXTERN    VDHRegisterAPI : NEAR 
VDDName       DD   ?      ;    Pointer   to   the   name   of   the   virtual   device   driver 
pfnV86Hook    DD   ?      ;    V86 - mode   hook   routine   address 
pfnVPMHook    DD   ?      ;    VPM - mode   hook   routine   address 

PUSH      VDDName       ;    Push   VDDName 
PUSH      pfnV86Hook    ;    Push   pfnV86Hook 
PUSH      pfnVPMHook    ;    Push   pfnVPMHook 

CALL      VDHRegisterAPI     ;   Call   the   function

VDHRegisterAPI Parameter - VDDName

VDDName(DD) Pointer to the name of the virtual device driver. Maximum length is MAXLENXDD.

VDHRegisterAPI Parameter - pfnV86Hook

pfnV86Hook(DD) V86-mode hook routine address (NULL if no V86-mode handler is needed).

VDHRegisterAPI Parameter - pfnVPMHook

pfnVPMHook(DD) VPM-mode hook routine address (NULL if no VPM-mode handler is needed).

VDHRegisterAPI Return Value - rc

Success Returns TRUE

Failure Returns FALSE

VDHRegisterAPI - Parameters

VDDName(DD) Pointer to the name of the virtual device driver. Maximum length is MAXLENXDD.

pfnV86Hook(DD) V86-mode hook routine address (NULL if no V86-mode handler is needed).

pfnVPMHook(DD) VPM-mode hook routine address (NULL if no VPM-mode handler is needed).

VDHRegisterAPI - Purpose

Context Issues: This function can only be called in the DOS session-task context.

DOS Session Terminations: There are no DOS session termination implications for this function. The hook(s) are freed when the DOS session is terminated .

Notes:

Hook routine:

HookRoutine PROC NEAR
; PARAMETERS
;    ENTRY    [ESP + 8] - p - reserved
;             [ESP + 4] - 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 . inc 

EXTERN    VDHRegisterDMAChannel : NEAR 
DMAChannel        DD   ?      ;    DMA   channel 
DMAHandlerFunc    DD   ?      ;    The   virtual   device   driver ' s   DMA - handling   routine 

PUSH      DMAChannel        ;    Push   DMAChannel 
PUSH      DMAHandlerFunc    ;    Push   DMAHandlerFunc 

CALL      VDHRegisterDMAChannel         ;   Call   the   function

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

EXTERN    VDHRegisterDMAChannel : NEAR 
DMAChannel        DD   ?      ;    DMA   channel 
DMAHandlerFunc    DD   ?      ;    The   virtual   device   driver ' s   DMA - handling   routine 

PUSH      DMAChannel        ;    Push   DMAChannel 
PUSH      DMAHandlerFunc    ;    Push   DMAHandlerFunc 

CALL      VDHRegisterDMAChannel         ;   Call   the   function

VDHRegisterDMAChannel Parameter - DMAChannel

DMAChannel(DD) DMA channel.

VDHRegisterDMAChannel Parameter - DMAHandlerFunc

DMAHandlerFunc(DD) The virtual device driver's DMA-handler function.

The interface for the DMA-handler routine is as follows:

DMAHandler  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm   - DOS session requesting DMA
;           [ESP + 4] - iEvent - VDD_DMA_MASKOFF (Start DMA, Event)
;                                VDD_DMA_MASK    (Stop  DMA, Event)
;    EXIT   SUCCESS - Returns nonzero in EAX
;                     If VDD_DMA_MASKOFF,
;                        the virtual DMA device driver will program the DMA
;                     If VDD_DMA_MASK, don't care
;           FAILURE - Returns 0 (zero) in EAX

VDHRegisterDMAChannel Return Value - rc

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(DD) DMA channel.

DMAHandlerFunc(DD) The virtual device driver's DMA-handler function.

The interface for the DMA-handler routine is as follows:

DMAHandler  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 8] - hvdm   - DOS session requesting DMA
;           [ESP + 4] - iEvent - VDD_DMA_MASKOFF (Start DMA, Event)
;                                VDD_DMA_MASK    (Stop  DMA, Event)
;    EXIT   SUCCESS - Returns nonzero in EAX
;                     If VDD_DMA_MASKOFF,
;                        the virtual DMA device driver will program the DMA
;                     If VDD_DMA_MASK, don't care
;           FAILURE - Returns 0 (zero) in EAX

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

EXTERN    VDHRegisterProperty : NEAR 
PropertyName       DD   ?      ;    Property   name   pointer 
Reserved           DD   ?      ;    Must   be   set   to   0 
Reserved           DD   ?      ;    Must   be   set   to   0 
PropertyType       DW   ?      ;    Property   type 
PropertyOrdinal    DW   ?      ;    Property   ordinal 
PropertyFlag       DD   ?      ;    Property   flag 
DefaultValue       DD   ?      ;    Default   value   of   the   property 
ValidationData     DD   ?      ;    Validation   data 
ValidationFunc     DD   ?      ;    Pointer   to   a   virtual   device   driver   property   function 

PUSH      PropertyName       ;    Push   PropertyName 
PUSH      Reserved           ;    Push   Reserved 
PUSH      Reserved           ;    Push   Reserved 
PUSH      PropertyType       ;    Push   PropertyType 
PUSH      PropertyOrdinal    ;    Push   PropertyOrdinal 
PUSH      PropertyFlag       ;    Push   PropertyFlag 
PUSH      DefaultValue       ;    Push   DefaultValue 
PUSH      ValidationData     ;    Push   ValidationData 
PUSH      ValidationFunc     ;    Push   ValidationFunc 

CALL      VDHRegisterProperty          ;   Call   the   function

VDHRegisterProperty - Format

/*

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

include   mvdm . inc 

EXTERN    VDHRegisterProperty : NEAR 
PropertyName       DD   ?      ;    Property   name   pointer 
Reserved           DD   ?      ;    Must   be   set   to   0 
Reserved           DD   ?      ;    Must   be   set   to   0 
PropertyType       DW   ?      ;    Property   type 
PropertyOrdinal    DW   ?      ;    Property   ordinal 
PropertyFlag       DD   ?      ;    Property   flag 
DefaultValue       DD   ?      ;    Default   value   of   the   property 
ValidationData     DD   ?      ;    Validation   data 
ValidationFunc     DD   ?      ;    Pointer   to   a   virtual   device   driver   property   function 

PUSH      PropertyName       ;    Push   PropertyName 
PUSH      Reserved           ;    Push   Reserved 
PUSH      Reserved           ;    Push   Reserved 
PUSH      PropertyType       ;    Push   PropertyType 
PUSH      PropertyOrdinal    ;    Push   PropertyOrdinal 
PUSH      PropertyFlag       ;    Push   PropertyFlag 
PUSH      DefaultValue       ;    Push   DefaultValue 
PUSH      ValidationData     ;    Push   ValidationData 
PUSH      ValidationFunc     ;    Push   ValidationFunc 

CALL      VDHRegisterProperty          ;   Call   the   function

VDHRegisterProperty Parameter - PropertyName

PropertyName(DD) Pointer to an ASCIIZ string containing the property name. Maximum length is 40 characters.

VDHRegisterProperty Parameter - Reserved

Reserved(DD) Must be set to 0 (zero).

VDHRegisterProperty Parameter - Reserved

Reserved(DD) Must be set to 0 (zero).

VDHRegisterProperty Parameter - PropertyType

PropertyType(DW) Property type.

Values are:

VDMP_BOOL 0-Boolean
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(DW) 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(DD) Property flag.

Possible value:

VDMP_CREATE Property can be specified only at DOS session creation. Any change to the property after DOS session creation is ignored.

VDHRegisterProperty Parameter - DefaultValue

DefaultValue(DD) Default value of the property.

The format of this field depends on the value of PropertyType:

VDMP_BOOL DefaultValue is interpreted as a BOOL (Boolean) value.
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(DD) Validation data.

The value of this field depends on the value of PropertyType.

VDMP_BOOL ValidationData is NULL. The user is expected to validate Booleans .

VDMP_INT ValidationData is a pointer to a VPBOUND structure:

VPBOUND Limits for VDMP_INT properties. Note that maximum >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:

VPBOUND_s STRUC
    min    DW   ?   ; minimum allowed value
    max    DW   ?   ; maximum allowed value
    step   DW   ?   ; increment between values
VPBOUND_s ENDS

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(DD) Function that validates and accepts changes to this property for a running DOS session. Ignored if VDMP_CREATE is specified in conjunction with VDMP_BOOL, VDMP_INT, or VDMP_ENUM.

The interface for the ValidationFunc is defined as follows:

VDHPROP_VALIDATE  EQU  0x00000000L
VDHPROP_SET       EQU  0x00000001L

ValidationFunc  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - op (DD)
;           [ESP + 12] - hvdm (DD)
;           [ESP +  8] - cb (DD)
;           [ESP +  4] - pch (DD)

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              DD              Operation to perform.  See the following
                                parameter.

hvdm            DD              Handle of DOS session.  Undefined if op =
                                VDHPROP_VALIDATE.

cb              DD              Count of bytes pointed by pch.  See the
                                following parameter.

pch             DD              Pointer to the value set or validate. See the
                                following parameter.

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

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(DD) Pointer to an ASCIIZ string containing the property name. Maximum length is 40 characters.

Reserved(DD) Must be set to 0 (zero).

PropertyType(DW) 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(DW) 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(DD) Property flag.

Possible value:

VDMP_CREATE Property can be specified only at DOS session creation. Any change to the property after DOS session creation is ignored.

DefaultValue(DD) Default value of the property.

The format of this field depends on the value of PropertyType:

VDMP_BOOL DefaultValue is interpreted as a BOOL (Boolean) value.
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(DD) Validation data.

The value of this field depends on the value of PropertyType.

VDMP_BOOL ValidationData is NULL. The user is expected to validate Booleans .

VDMP_INT ValidationData is a pointer to a VPBOUND structure:

VPBOUND Limits for VDMP_INT properties. Note that maximum >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:

VPBOUND_s STRUC
    min    DW   ?   ; minimum allowed value
    max    DW   ?   ; maximum allowed value
    step   DW   ?   ; increment between values
VPBOUND_s ENDS

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(DD) Function that validates and accepts changes to this property for a running DOS session. Ignored if VDMP_CREATE is specified in conjunction with VDMP_BOOL, VDMP_INT, or VDMP_ENUM.

The interface for the ValidationFunc is defined as follows:

VDHPROP_VALIDATE  EQU  0x00000000L
VDHPROP_SET       EQU  0x00000001L

ValidationFunc  PROC  NEAR
; PARAMETERS
;    ENTRY  [ESP + 16] - op (DD)
;           [ESP + 12] - hvdm (DD)
;           [ESP +  8] - cb (DD)
;           [ESP +  4] - pch (DD)

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              DD              Operation to perform.  See the following
                                parameter.

hvdm            DD              Handle of DOS session.  Undefined if op =
                                VDHPROP_VALIDATE.

cb              DD              Count of bytes pointed by pch.  See the
                                following parameter.

pch             DD              Pointer to the value set or validate. See the
                                following parameter.