## Virtual Device Driver Reference for OS/2

[prev][next][parent][TOC]

### Some Notes on Virtual DevHlp Services

Passing Addresses of Buffers

The SSToDS macro must be used when passing the address of a frame ( automatic) variable in a function call because the 32-bit code assumes SS= DS. Pointers allocated from the stack must be DS-relative.

Function Definitions and Calling Conventions

All virtual DevHlp services are 32-bit NEAR functions. For a description of the calling conventions, refer to the function prototype definition VDHENTRY located in the MVDM.INC include file included with the Developer's Toolkit for OS/2.

When using the virtual DevHlp services, the function being called is responsible for cleaning up the stack. This means that when you call a virtual DevHlp service, the function you call cleans up the stack; you do not have to pop the parameters off the stack after the call. This also means that when you register a hook (or callback) routine with a virtual DevHlp service, your hook routine is responsible for cleaning up the stack before it returns to the function that called it.

The virtual DevHlp services are called directly, as in CALL VDHFunction. This is in contrast to the physical device driver Device Helper services, which are called indirectly as in CALL [DevHlpFunction].

Syntax Examples

The syntax examples are shown in C language. For assembler language syntax examples, see Assembler Language Syntax.

Defined Constants and Type Definitions

Defined constants, that is, equate statements in an include file, and type definitions are widely used in OS/2. These constant values are defined in the master header files, MVDM.INC or .h, or in one of the files that MVDM. INC or .h includes. The defined constants and type definitions that are seen in the syntax examples should be used to provide a degree of machine and version independence.

Invalid Parameters and System Halts

In many of the virtual DevHlp functions, invalid parameters or other error conditions often cause a system halt because virtual device drivers run at Ring 0 and have free access to everything in the system.

Remarks Section

Each function description has a Remarks section at the end, which consists of three parts:

Context Issues: Indicates the specific contexts in which virtual DevHlps should be called.

DOS Session Termination: Indicates what the virtual device driver must do upon termination of a DOS session, for example, release resources.

Notes: These are miscellaneous function-specific notes about the function.