Index of Topics

- 1 -

16-bit OS/2:  Building and Running the Sample OS/2 1.x Application
16-bit OS/2:  Creating 16-bit OS/2 1.x Applications
16-bit OS/2:  Debugging the Sample OS/2 1.x Application
16-bit OS/2:  The Sample Application
16-bit Windows:  Building and Running the GUI Application
16-bit Windows:  Building and Running the Non-GUI Application
16-bit Windows:  Console Device in a Windowed Environment
16-bit Windows:  Creating 16-bit Windows 3.x Applications
16-bit Windows:  Debugging the GUI Application
16-bit Windows:  Debugging the Non-GUI Application
16-bit Windows:  Default Windowing Library Functions
16-bit Windows:  Porting Non-GUI Applications to 16-bit Windows 3.x
16-bit Windows:  The Sample GUI Application
16-bit Windows:  The Sample Non-GUI Application

- 3 -

32-bit Extended DOS Application Development
32-bit OS/2:  Building and Running the Sample OS/2 Application
32-bit OS/2:  Creating 32-bit OS/2 Applications
32-bit OS/2:  Debugging the Sample OS/2 Application
32-bit OS/2:  The Sample Application
32-bit Windows:  Building and Running the GUI Application
32-bit Windows:  Building and Running the Non-GUI Application
32-bit Windows:  Console Device in a Windowed Environment
32-bit Windows:  Creating 32-bit Windows 3.x Applications
32-bit Windows:  Debugging the GUI Application
32-bit Windows:  Debugging the Non-GUI Application
32-bit Windows:  Default Windowing Library Functions
32-bit Windows:  Porting Non-GUI Applications to 32-bit Windows 3.x
32-bit Windows:  The Sample GUI Application
32-bit Windows:  The Sample Non-GUI Application

- A -

Argument Passing Convention

- C -

Commonly Asked Questions and Answers
The compiler cannot find my include files
Converting to Open Watcom F77
Creating NetWare 386 NLM Applications

- D -

The difference between the "d1" and "d2" compiler options
The difference between the "debug" and "d2" compiler options
DOS/4GW:  32-Bit Gates
DOS/4GW:  Access to Technical Support
DOS/4GW:  Addressing
DOS/4GW:  Building and Running the Sample DOS/4GW Application
DOS/4GW:  Chaining 16-bit and 32-bit Handlers
DOS/4GW:  Changing the Defaults
DOS/4GW:  Changing the Switch Mode Setting
DOS/4GW:  Compatibility
DOS/4GW:  Configuring DOS/4GW
DOS/4GW:  Controlling Address Line 20
DOS/4GW:  Coprocessor Status
DOS/4GW:  Creating 32-bit DOS/4GW Applications
DOS/4GW:  Debugging
DOS/4GW:  Debugging the Sample DOS/4GW Application
DOS/4GW:  Demand Paging Performance Tuning Services
DOS/4GW:  Differences Within the DOS/4G Product Line
DOS/4GW:  DOS Memory Management Services
DOS/4GW:  DOS, BIOS, and Mouse Services
DOS/4GW:  DOS/4G Errors
DOS/4GW:  DOS/4GW Commonly Asked Questions
DOS/4GW:  DOS4GW
DOS/4GW:  DPMI Version
DOS/4GW:  Error Messages
DOS/4GW:  Fine Control of Memory Usage
DOS/4GW:  Functions 25H and 35H:  Interrupt Handling in Protected Mode
DOS/4GW:  Getting the Address of the Interrupt Handler
DOS/4GW:  Int31H Function Calls
DOS/4GW:  Interrupt 21H Functions
DOS/4GW:  Interrupt 31H DPMI Functions
DOS/4GW:  Interrupt and Exception Handling
DOS/4GW:  Interrupt Services
DOS/4GW:  Kernel Error Messages
DOS/4GW:  Linear Executables
DOS/4GW:  Local Descriptor Table (LDT) Management Services
DOS/4GW:  Memory Management
DOS/4GW:  Memory Management Services
DOS/4GW:  Memory Use
DOS/4GW:  Page Locking Services
DOS/4GW:  Physical Address Mapping
DOS/4GW:  PMINFO
DOS/4GW:  PRIVATXM
DOS/4GW:  RMINFO
DOS/4GW:  Setting Runtime Options
DOS/4GW:  Specifying a Range of Extended Memory
DOS/4GW:  The .VMC File
DOS/4GW:  The DOS4G Environment Variable
DOS/4GW:  The Linear Executable Format
DOS/4GW:  The Sample Application
DOS/4GW:  The Stub Program
DOS/4GW:  The Tenberry Software DOS/4GW DOS Extender
DOS/4GW:  Translation Services
DOS/4GW:  Using Extra Memory
DOS/4GW:  Using Interrupt 31H Function Calls
DOS/4GW:  Utilities
DOS/4GW:  Vendor Specific Extensions
DOS/4GW:  Virtual Interrupt State Functions
DOS/4GW:  Virtual Memory
DOS/4GW:  VMM
DOS/4GW:  VMM Default Parameters
DOS:  Building and Running the Sample DOS Application
DOS:  Creating 16-bit DOS Applications
DOS:  Debugging the Sample DOS Application
DOS:  The Sample Application

- H -

How can I write directly to video memory using a DOS extender?
How do I access a FORTRAN common block from within C?
How do I call a C function that accepts a variable number of arguments?
How do I get information about free memory in the 32-bit environment?
How do I issue interrupts in a DOS/4GW application?
How do I pass a string from a C function to FORTRAN?
How do I pass a string from FORTRAN to a C function?
How do I pass integers from C to a FORTRAN function?
How do I pass integers from FORTRAN to a C function?
How more than 20 files at a time can be opened
How source files can be seen in the debugger

- I -

Integer Type Compatibility
Inter-Language calls:  C and FORTRAN

- L -

The linker reports a "stack segment not found" error
Linking Considerations

- M -

Memory Model Compatibility

- N -

NT:  A Multi-threaded Example
NT:  Building and Running the Character-mode Application
NT:  Creating a New Thread
NT:  Creating a Sample Dynamic Link Library
NT:  Creating Dynamic Link Libraries
NT:  Creating Threads
NT:  Creating Windows NT Character-mode Applications
NT:  Debugging the Character-mode Application
NT:  Dynamic Link Library Initialization/Termination
NT:  Getting the Current Thread Identifier
NT:  Programming Considerations
NT:  Terminating the Current Thread
NT:  The Dynamic Link Library Data Area
NT:  The Sample Character-mode Application
NT:  Using Dynamic Link Libraries
NT:  Windows NT Character-mode Versus GUI
NT:  Windows NT Dynamic Link Libraries
NT:  Windows NT Multi-threaded Applications
NT:  Windows NT Programming Overview

- O -

Open Watcom FORTRAN 77 Application Development
OS/2:  A Multi-threaded Example
OS/2:  An Example
OS/2:  Calling Presentation Manager API Functions
OS/2:  Creating a New Thread
OS/2:  Creating a Sample Dynamic Link Library
OS/2:  Creating Dynamic Link Libraries
OS/2:  Creating Threads
OS/2:  Dynamic Link Library Initialization/Termination
OS/2:  Getting the Current Thread Identifier
OS/2:  OS/2 2.x Dynamic Link Libraries
OS/2:  OS/2 2.x Multi-threaded Applications
OS/2:  Porting Existing FORTRAN 77 Applications
OS/2:  Programming Considerations
OS/2:  Programming for OS/2 Presentation Manager
OS/2:  Terminating the Current Thread
OS/2:  The Dynamic Link Library Data Area
OS/2:  Thread Limits
OS/2:  Using Dynamic Link Libraries

- P -

Phar Lap:  Building and Running the Sample 386|DOS-Extender Application
Phar Lap:  Creating 32-bit Phar Lap 386|DOS-Extender Applications
Phar Lap:  Debugging the Sample 386|DOS-Extender Application
Phar Lap:  The Sample Application

- R -

Reading a stream of binary data from a file
Redefining math error handling with Open Watcom F77
Resolving an "Undefined Reference" linker error

- S -

Special Windows API Functions
Symbol Naming Convention

- W -

What "Stack Overflow!" means
What are the probable causes of a General Protection Fault in 32-bit applications?
What you should know about optimization
Which floating-point compiler option should I use for my application?
Why local variable values are not maintained between subprogram calls
Windows:  32-bit Extended Windows Application Development
Windows:  _16 Functions
Windows:  _Call16
Windows:  A Sample 32-bit DLL
Windows:  A Sample 32-bit DLL Using a Structure
Windows:  A Working Example
Windows:  AllocAlias16
Windows:  AllocHugeAlias16
Windows:  Building the Applications
Windows:  Callback Function Pointers
Windows:  Calling 16-bit DLLs
Windows:  Calling Functions in a 32-bit DLL from a 16-bit Application
Windows:  Calling Functions in a 32-bit DLL from a 32-bit Application
Windows:  Can you call 16-bit code from a 32-bit code?
Windows:  Compiling and Linking the Examples
Windows:  Creating and Debugging Dynamic Link Libraries
Windows:  Debugging a 32-bit DLL
Windows:  DefineDLLEntry
Windows:  DefineUserProc16
Windows:  Environment Notes
Windows:  Floating-point Emulation
Windows:  FreeAlias16
Windows:  FreeHugeAlias16
Windows:  FreeIndirectFunctionHandle
Windows:  GetIndirectFunctionHandle
Windows:  GetProc16
Windows:  GlobalAlloc and LocalAlloc
Windows:  How do I add my Windows resources?
Windows:  Implementation Overview
Windows:  Installing the Examples under Windows
Windows:  Interfacing Visual Basic and Open Watcom FORTRAN 77 DLLs
Windows:  InvokeIndirectFunction
Windows:  MapAliasToFlat
Windows:  Multiple Instances
Windows:  PASS_WORD_AS_POINTER
Windows:  Pointer Handling
Windows:  Pointers
Windows:  ReleaseProc16
Windows:  Running the Examples
Windows:  Sample Visual Basic DLL Programs
Windows:  SendMessage and SendDlgItemMessage
Windows:  Source code for COVER16.DLL
Windows:  Source Code for VBDLL32.DLL
Windows:  Steps to Obtaining a 32-bit Application
Windows:  Summary
Windows:  System Overview
Windows:  System Structure
Windows:  The Open Watcom 32-bit Windows 3.x Extender
Windows:  What size of function pointers passed to Windows?
Windows:  When To Convert Incoming Pointers
Windows:  When To Convert Outgoing Pointers
Windows:  Why are 32-bit callback routines FAR?
Windows:  Why use the _16 API functions?
Windows:  WIN386 Library Subprograms
Windows:  WINAPI.FI
Windows:  Window Sub-classing
Windows:  Windows 3.x 32-bit Programming Overview
Windows:  Windows 32-Bit Dynamic Link Libraries

Open Watcom FORTRAN 77 Application Development

• DOS Programming Guide

  Creating 16-bit DOS Applications

  
  Creating 32-bit Phar Lap 386|DOS-Extender Applications

  
  Creating 32-bit DOS/4GW Applications

  
  32-bit Extended DOS Application Development

• The DOS/4GW DOS Extender

  The Tenberry Software DOS/4GW DOS Extender

  
  Linear Executables

  
  Configuring DOS/4GW

  
  VMM

  
  Interrupt 21H Functions

  
  Interrupt 31H DPMI Functions

  
  Utilities

  
  Error Messages

  
  DOS/4GW Commonly Asked Questions

• Windows 3.x Programming Guide

  Creating 16-bit Windows 3.x Applications

  
  Porting Non-GUI Applications to 16-bit Windows 3.x

  
  Creating 32-bit Windows 3.x Applications

  
  Porting Non-GUI Applications to 32-bit Windows 3.x

  
  The Open Watcom 32-bit Windows Extender

  
  Windows 3.x 32-bit Programming Overview

  
  Windows 32-Bit Dynamic Link Libraries

  
  Interfacing Visual Basic and Open Watcom FORTRAN 77 DLLs

  
  WIN386 Library Subprograms

  
  32-bit Extended Windows Application Development

  
  Special Windows API Functions

• Windows NT Programming Guide

  Windows NT Programming Overview

  
  Creating Windows NT GUI Applications

  
  Porting Non-GUI Applications to Windows NT GUI

  
  Windows NT Multi-threaded Applications

  
  Windows NT Dynamic Link Libraries

• OS/2 Programming Guide

  Creating 16-bit OS/2 1.x Applications

  
  Creating 32-bit OS/2 Applications

  
  OS/2 Multi-threaded Applications

  
  OS/2 Dynamic Link Libraries

  
  Programming for OS/2 Presentation Manager

• Novell NLM Programming Guide

  Creating NetWare 386 NLM Applications

• Mixed Language Programming

  Inter-Language calls:  C and FORTRAN

• Common Problems

  Commonly Asked Questions and Answers

DOS:  Creating 16-bit DOS Applications

DOS:  The Sample Application

DOS:  Building and Running the Sample DOS Application

DOS:  Debugging the Sample DOS Application

Phar Lap:  Creating 32-bit Phar Lap 386|DOS-Extender Applications

Phar Lap:  The Sample Application

Phar Lap:  Building and Running the Sample 386|DOS-Extender Application

Phar Lap:  Debugging the Sample 386|DOS-Extender Application

DOS/4GW:  Creating 32-bit DOS/4GW Applications

DOS/4GW:  The Sample Application

DOS/4GW:  Building and Running the Sample DOS/4GW Application

DOS/4GW:  Debugging the Sample DOS/4GW Application

32-bit Extended DOS Application Development

• How can I write directly to video memory using DOS/4GW?
• How do I issue interrupts in a DOS/4GW application?
• How do I get information about free memory with DOS/4GW?

How can I write directly to video memory using a DOS extender?

How do I issue interrupts in a DOS/4GW application?

How do I get information about free memory in the 32-bit environment?

DOS/4GW:  The Tenberry Software DOS/4GW DOS Extender

• DOS/4GW will only execute programs built with a Open Watcom 32-bit compiler such as Open Watcom F77 and linked with its run-time libraries.
• The DOS/4GW virtual memory manager (VMM), included in the package, is restricted to 32MB of memory.
• DOS/4GW does not provide extra functionality such as TSR capability and VMM performance tuning enhancements.

DOS/4GW:  Linear Executables

DOS/4GW:  The Linear Executable Format

DOS/4GW:  The Stub Program

• make the stub program do a checksum on the "DOS4GW.EXE" file to make sure it's the correct version.
• copy protect your program.
• specify a search path for the "DOS4GW.EXE" file.
• add command line arguments.

DOS/4GW:  Memory Use

DOS/4GW:  Configuring DOS/4GW

DOS/4GW:  The DOS4G Environment Variable

Options:

QUIET

Use this option to suppress the DOS/4GW banner.
The banner that is displayed by DOS/4GW at startup can be suppressed by issuing the following command:

     
     set DOS4G=quiet

Note:  Use of the quiet switch is only permitted pursuant to the terms and conditions of the WATCOM Software License Agreement and the additional redistribution rights described in the Getting Started manual.   Under these terms, suppression of the copyright by using the quiet switch is not permitted for applications which you distribute to others.

VERBOSE

Use this option to maximize the information available for postmortem debugging.
Before running your application, issue the following command:

     
     set DOS4G=verbose

Reproduce the crash and record the output.

NULLP

Use this option to trap references to the first sixteen bytes of physical memory.
Before running your application, issue the following command:

     
     set DOS4G=nullp

DOS/4GW:  Changing the Switch Mode Setting

1. If you have one of the machines listed below, set the DOS16M environment variable to the value shown for that machine and specify a range of extended memory.  For example, if your machine is a NEC 98-series, set DOS16M=1 @2M-4M.   See the section entitled DOS/4GW:  Fine Control of Memory Usage in this chapter for more information about setting the memory range.
   
            Machine               Setting 
   
            NEC 98-series        1        
            Fujitsu FMR-60,-70   5        
            Hitachi B32          14       
            OKI if800             15      
   
   Before running DOS/4GW applications, check the switch mode setting by following this procedure:
2. Run PMINFO and note the switch setting reported on the last line of the display.  (PMINFO, which reports on the protected-mode resources available to your programs, is described in more detail in the chapter entitled DOS/4GW:  Utilities)
   
   If PMINFO runs, the setting is usable on your machine.
3. If you changed the switch setting, add the new setting to your AUTOEXEC.BAT file.

DOS/4GW:  Fine Control of Memory Usage

DOS/4GW:  Specifying a Range of Extended Memory

• You are running on a Fujitsu FMR-series, NEC 98-series, OKI if800-series or Hitachi B-series machine.
• You have older programs that use extended memory but don't follow one of the standard disciplines.
• You want to shell out of DOS/4GW to use another program that requires extended memory.

set DOS16M= 1 @2m-4m

Mode 1, for NEC 98-series machines, and use extended memory between 2.0 and 4.0MB.

set DOS16M= :1M

Use the last full megabyte of extended memory, or as much as available limited to 1MB.

set DOS16M= @2m

Use any extended memory available above 2MB.

set DOS16M= @ 0 - 5m

Use any available extended memory from 0.0 (really 1.0) to 5.0MB.

set DOS16M= :0

Use no extended memory.

DOS/4GW:  Using Extra Memory

DOS/4GW:  Setting Runtime Options

0x01

check A20 line -- This option forces DOS/4GW to wait until the A20 line is enabled before switching to protected mode.  When DOS/4GW switches to real mode, this option suspends your program's execution until the A20 line is disabled, unless an XMS manager (such as HIMEM.SYS) is active.  If an XMS manager is running, your program's execution is suspended until the A20 line is restored to the state it had when the CPU was last in real mode.  Specify this option if you have a machine that runs DOS/4GW but is not truly AT-compatible.  For more information on the A20 line, see the section entitled DOS/4GW:  Controlling Address Line 20.

0x02

prevent initialization of VCPI -- By default, DOS/4GW searches for a VCPI server and, if one is present, forces it on.  This option is useful if your application does not use EMS explicitly, is not a resident program, and may be used with 386-based EMS simulator software.

0x04

directly pass down keyboard status calls -- When this option is set, status requests are passed down immediately and unconditionally.  When disabled, pass-downs are limited so the 8042 auxiliary processor does not become overloaded by keyboard polling loops.

0x10

restore only changed interrupts -- Normally, when a DOS/4GW program terminates, all interrupts are restored to the values they had at the time of program startup.  When you use this option, only the interrupts changed by the DOS/4GW program are restored.

0x20

set new memory to 00 -- When DOS/4GW allocates a new segment or increases the size of a segment, the memory is zeroed.  This can help you find bugs having to do with uninitialized memory.  You can also use it to provide a consistent working environment regardless of what programs were run earlier.  This option only affects segment allocations or expansions that are made through the DOS/4GW kernel (with DOS function 48H or 4AH).  This option does not affect memory allocated with a compiler's malloc function.

0x40

set new memory to FF -- When DOS/4GW allocates a new segment or increases the size of a segment, the memory is set to 0xFF bytes.  This is helpful in making reproducible cases of bugs caused by using uninitialized memory.  This option only affects segment allocations or expansions that are made through the DOS/4GW kernel (with DOS function 48H or 4AH).  This option does not affect memory allocated with a compiler's malloc function.

0x80

new selector rotation -- When DOS/4GW allocates a new selector, it usually looks for the first available (unused) selector in numerical order starting with the highest selector used when the program was loaded.  When this option is set, the new selector search begins after the last selector that was allocated.  This causes new selectors to rotate through the range.  Use this option to find references to stale selectors, i.e., segments that have been cancelled or freed.

DOS/4GW:  Controlling Address Line 20

DOS/4GW:  VMM

DOS/4GW:  VMM Default Parameters

MINMEM

The minimum amount of RAM managed by VMM.  The default is 512KB.

MAXMEM

The maximum amount of RAM managed by VMM.  The default is 4MB.

SWAPMIN

The minimum or initial size of the swap file.  If this option is not used, the size of the swap file is based on VIRTUALSIZE (see below).

SWAPINC

The size by which the swap file grows.

SWAPNAME

The swap file name.  The default name is "DOS4GVM.SWP".  By default the file is in the root directory of the current drive.  Specify the complete path name if you want to keep the swap file somewhere else.

DELETESWAP

Whether the swap file is deleted when your program exits.  By default the file is not deleted.  Program startup is quicker if the file is not deleted.

VIRTUALSIZE

The size of the virtual memory space.  The default is 16MB.

DOS/4GW:  Changing the Defaults

1. Specify different parameter values as arguments to the DOS4GVM environment variable, as shown in the example below.
   
        
        set DOS4GVM=deleteswap maxmem#8192
2. Create a configuration file with the filetype extension ".VMC", and use that as an argument to the DOS4GVM environment variable, as shown below.
   
        
        set DOS4GVM=@NEW4G.VMC

DOS/4GW:  The .VMC File

DOS/4GW:  Interrupt 21H Functions

• When you pass a parameter to an Interrupt 21H function that expects a 16-bit quantity in a general register (for example, AX), pass a 32-bit quantity in the corresponding extended register (for example, EAX).  When a DOS function returns a 16-bit quantity in a general register, expect to receive it (with high-order zero bits) in the corresponding extended register.
• When an Interrupt 21H function expects to receive a 16:16 pointer in a segment:general register pair (for example, ES:BX), supply a 16:32 pointer using the same segment register and the corresponding extended general register (ES:EBX).  DOS/4GW will copy data and translate pointers so that DOS ultimately receives a 16:16 real-mode pointer in the correct registers.
• When DOS returns a 16:16 real-mode pointer, DOS/4GW translates the segment value into an appropriate protected-mode selector and generates a 32-bit offset that results in a 16:32 pointer to the same location in the linear address space.
• Many DOS functions return an error code in AX if the function fails.  DOS/4GW checks the status of the carry flag, and if it is set, indicating an error, zero-extends the code for EAX.  It does not change any other registers.
• If the value is passed or returned in an 8-bit register (AL or AH, for example), DOS/4GW puts the value in the appropriate location and leaves the upper half of the 32-bit register untouched.

1. For Function 29H, DS:ESI and ES:EDI contain pointer values that are not changed by the call.
2. You can read and write quantities larger than 64KB with Functions 3FH and 40H.  DOS/4GW breaks your request into chunks smaller than 64KB, and calls the DOS function once for each chunk.
3. You can't transfer more than 64KB using Function 44h, subfunctions 02H, 03H, 04H, or 05H.  DOS/4GW does not break larger requests into DOS-sized chunks, as it does for Functions 3FH and 40H.
4. When you call Function 4B under DOS/4GW, you pass it a data structure that contains 16:32 bit pointers.  DOS/4GW translates these into 16:16 bit pointers in the structure it passes to DOS.

DOS/4GW:  Functions 25H and 35H:  Interrupt Handling in Protected Mode

DOS/4GW:  32-Bit Gates

DOS/4GW:  Chaining 16-bit and 32-bit Handlers

DOS/4GW:  Getting the Address of the Interrupt Handler

DOS/4GW:  Interrupt 31H DPMI Functions

DOS/4GW:  Using Interrupt 31H Function Calls

• All Interrupt 31H calls modify the AX register.  Unsupported or unsuccessful calls return an error code in AX.  Other registers are saved unless they contain specified return values.
• All Interrupt 31H calls modify flags:  Unsupported or unsuccessful calls return with the carry flag set.  Successful calls clear the carry flag.  Only memory management and interrupt flag management calls modify the interrupt flag.
• Memory management calls can enable interrupts.
• All calls are reentrant.

DOS/4GW:  Int31H Function Calls

• Local Descriptor Table (LDT) management services
• DOS memory management services
• Interrupt services
• Translation services
• DPMI version
• Memory management services
• Page locking services
• Demand paging performance tuning services
• Physical address mapping
• Virtual interrupt state functions
• Vendor specific extensions
• Coprocessor status

DOS/4GW:  Local Descriptor Table (LDT) Management Services

Function 0000H

This function allocates a specified number of descriptors from the LDT and returns the base selector.  Pass the following information:

AX = 0000H

CX = number of descriptors to be allocated

If the call succeeds, the carry flag is clear and the base selector is returned in AX.  If the call fails, the carry flag is set.

An allocated descriptor is set to the present data type, with a base and limit of zero.  The privilege level of an allocated descriptor is set to match the code segment privilege level of the application.  To find out the privilege level of a descriptor, use the lar instruction.

Allocated descriptors must be filled in by the application.  If more than one descriptor is allocated, the returned selector is the first of a contiguous array.  Use Function 0003H to get the increment for the next selector in the array.

Function 0001H

This function frees the descriptor specified.  Pass the following information:

AX = 0001H

BX = the selector to free

Use the selector returned with function 0000h when the descriptor was allocated.  To free an array of descriptors, call this function for each descriptor.  Use Function 0003H to find out the increment for each descriptor in the array.

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set.

You can use this function to free the descriptors allocated for the program's initial CS, DS, and SS segments, but you should not free other segments that were not allocated with Function 0000H or Function 000DH.

Function 0002H

This function converts a real-mode segment to a descriptor that a protected-mode program can address.  Pass the following information:

AX = 0002H

BX = real-mode segment address

If the call succeeds, it clears the carry flag and returns the selector mapped to the real-mode segment in AX.  If the call fails, the carry flag is set.

If you call this function more than once with the same real-mode segment address, you get the same selector value each time.  The descriptor limit is set to 64KB.

The purpose of this function is to give protected-mode programs easy access to commonly used real-mode segments.  However, because you cannot modify or free descriptors created by this function, it should be used infrequently.  Do not use this function to get descriptors for private data areas.

To examine real-mode addresses using the same selector, first allocate a descriptor, and then use Function 0007H to change the linear base address.

Function 0003H

This function returns the increment value for the next selector.  Use this function to get the value you add to the base address of an allocated array of descriptors to get the next selector address.  Pass the following information:

AX = 0003H

This call always succeeds.  The increment value is returned in AX.  This value is always a power of two, but no other assumptions can be made.

Function 0006H

This function gets the linear base address of a selector.  Pass the following information:

AX = 0006H

BX = selector

If the call succeeds, the carry flag is clear and CX:DX contains the 32-bit linear base address of the segment.  If the call fails, it sets the carry flag.

If the selector you specify in BX is invalid, the call fails.

Function 0007H

This function changes the base address of a specified selector.  Only descriptors allocated through Function 0000H should be modified.  Pass the following information:

AX = 0007H

BX = selector

CX:DX = the new 32-bit linear base address for the segment

If the call succeeds, the carry flag is clear; if unsuccessful, the carry flag is set.

If the selector you specify in BX is invalid, the call fails.

Function 0008H

This function sets the upper limit of a specified segment.  Use this function to modify descriptors allocated with Function 0000H only.  Pass the following information:

AX = 0008H

BX = selector

CX:DX = 32-bit segment limit

If the call succeeds, the carry flag is clear; if unsuccessful, the carry flag is set.

The call fails if the specified selector is invalid, or if the specified limit cannot be set.

Segment limits greater than 1MB must be page-aligned.  This means that limits greater than 1MB must have the low 12 bits set.

To get the limit of a segment, use the 32-bit form of lsl for segment limits greater than 64KB.

Function 0009H

This function sets the descriptor access rights.  Use this function to modify descriptors allocated with Function 0000H only.  To examine the access rights of a descriptor, use the lar instruction.  Pass the following information:

AX = 0009H

BX = selector

CL = Access rights/type byte

CH = 386 extended access rights/type byte

If the call succeeds, the carry flag is clear; if unsuccessful, the carry flag is set.  If the selector you specify in BX is invalid, the call fails.  The call also fails if the access rights/type byte does not match the format and meet the requirements shown in the figures below.

The access rights/type byte passed in CL has the format shown in the figure below.


Figure 3. Access Rights/Type

The extended access rights/type byte passed in CH has the following format.


Figure 4. Extended Access Rights/Type

Function 000AH

This function creates an alias to a code segment.  This function creates a data descriptor that has the same base and limit as the specified code segment descriptor.  Pass the following information:

AX = 000AH

BX = code segment selector

If the call succeeds, the carry flag is clear and the new data selector is returned in AX.  If the call fails, the carry flag is set.  The call fails if the selector passed in BX is not a valid code segment.

To deallocate an alias to a code segment, use Function 0001H.

After the alias is created, it does not change if the code segment descriptor changes.  For example, if the base or limit of the code segment change later, the alias descriptor stays the same.

Function 000BH

This function copies the descriptor table entry for a specified descriptor.  The copy is written into an 8-byte buffer.   Pass the following information:

AX = 000BH

BX = selector

ES:EDI = a pointer to the 8-byte buffer for the descriptor copy

If the call succeeds, the carry flag is clear and ES:EDI contains a pointer to the buffer that contains a copy of the descriptor.  If the call fails, the carry flag is set.  The call fails if the selector passed in BX is invalid or unallocated.

Function 000CH

This function copies an 8-byte buffer into the LDT for a specified descriptor.  The descriptor must first have been allocated with Function 0000H.  Pass the following information:

AX = 000CH

BX = selector

ES:EDI = a pointer to the 8-byte buffer containing the descriptor

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set.  The call fails if the descriptor passed in BX is invalid.
The type byte, byte 5, has the same format and requirements as the access rights/type byte passed to Function 0009H in CL.  The format is shown in the first figure presented with the description of Function 0009H.

The extended type byte, byte 6, has the same format and requirements as the extended access rights/type byte passed to Function 0009H in CH, except that the limit field can have any value, and the low order bits marked reserved are used to set the upper 4 bits of the descriptor limit.  The format is shown in the second figure presented with the description of Function 0009H.

Function 000DH

This function allocates a specific LDT descriptor.  Pass the following information:

AX = 000DH

BX = selector

If the call succeeds, the carry flag is clear and the specified descriptor is allocated.  If the call fails, the carry flag is set.

The call fails if the specified selector is already in use, or if it is not a valid LDT descriptor.  The first 10h (16 decimal) descriptors are reserved for this function, and should not be used by the host.  Some of these descriptors may be in use, however, if another client application is already loaded.

To free the descriptor, use Function 0001H.

DOS/4GW:  DOS Memory Management Services

Function 0100H

This function allocates memory from the DOS free memory pool.  This function returns both the real-mode segment and one or more descriptors that can be used by protected-mode applications.  Pass the following information:

AX = 0100H

BX = the number of paragraphs (16-byte blocks) requested

If the call succeeds, the carry flag is clear.  AX contains the initial real-mode segment of the allocated block and DX contains the base selector for the allocated block.

If the call fails, the carry flag is set.  AX contains the DOS error code.  If memory is damaged, code 07H is returned.  If there is not enough memory to satisfy the request, code 08H is returned.  BX contains the number of paragraphs in the largest available block of DOS memory.

If you request a block larger than 64KB, contiguous descriptors are allocated.  Use Function 0003H to find the value of the increment to the next descriptor.  The limit of the first descriptor is set to the entire block.  Subsequent descriptors have a limit of 64KB, except for the final descriptor, which has a limit of blocksize MOD 64KB.

You cannot modify or deallocate descriptors allocated with this function.  Function 101H deallocates the descriptors automatically.

Function 0101H

This function frees a DOS memory block allocated with function 0100H.  Pass the following information:

AX = 0101H

DX = selector of the block to be freed

If the call succeeds, the carry flag is clear.

If the call fails, the carry flag is set and the DOS error code is returned in AX.  If the incorrect segment was specified, code 09H is returned.  If memory control blocks are damaged, code 07H is returned.

All descriptors allocated for the specified memory block are deallocated automatically and cannot be accessed correctly after the block is freed.

Function 0102H

This function resizes a DOS memory block allocated with function 0100H.  Pass the following information:

AX = 0102H

BX = the number of paragraphs (16-byte blocks) in the resized block

DX = selector of block to resize

If the call succeeds, the carry flag is clear.

If the call fails, the carry flag is set, the maximum number of paragraphs available is returned in BX, and the DOS error code is returned in AX.  If memory code blocks are damaged, code 07H is returned.  If there isn't enough memory to increase the size as requested, code 08H is returned.  If the incorrect segment is specified, code 09h is returned.

Because of the difficulty of finding additional contiguous memory or descriptors, this function is not often used to increase the size of a memory block.  Increasing the size of a memory block might well fail because other DOS allocations have used contiguous space.  If the next descriptor in the LDT is not free, allocation also fails when the size of a block grows over the 64KB boundary.

If you shrink the size of a memory block, you may also free some descriptors allocated to the block.  The initial selector remains unchanged, however; only the limits of subsequent selectors will change.

DOS/4GW:  Interrupt Services

Function 0200H

This function gets the value of the current task's real-mode interrupt vector for the specified interrupt.  Pass the following information:

AX = 0200H

BL = interrupt number

This call always succeeds.  All 100H (256 decimal) interrupt vectors are supported by the host.  When the call returns, the carry flag is clear, and the segment:offset of the real-mode interrupt handler is returned in CX:DX.

Because the address returned in CX is a segment, and not a selector, you cannot put it into a protected-mode segment register.  If you do, a general protection fault may occur.

Function 0201H

This function sets the value of the current task's real-mode interrupt vector for the specified interrupt.  Pass the following information:

AX = 0201H

BL = interrupt number

CX:DX = segment:offset of the real-mode interrupt handler

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set.

The address passed in CX:DX should be a real-mode segment:offset, such as function 0200H returns.  For this reason, the interrupt handler must reside in DOS addressable memory.  You can use Function 0100H to allocate DOS memory.  This version does not support the real-mode callback address function.

If you are hooking a hardware interrupt, you have to lock all segments involved.  These segments include the segment in which the interrupt handler runs, and any segment it may touch at interrupt time.

Function 0202H

This function gets the processor exception handler vector.  This function returns the CS:EIP of the current protected-mode exception handler for the specified exception number.  Pass the following information:

AX = 0202H

BL = exception/fault number (00h - 1Fh)

If the call succeeds, the carry flag is clear and the selector:offset of the protected-mode exception handler is returned in CX:EDX.  If it fails, the carry flag is set.

The value returned in CX is a valid protected-mode selector, not a real-mode segment.

Function 0203H

This function sets the processor exception handler vector.  This function allows protected-mode applications to intercept processor exceptions that are not handled by the DPMI environment.  Programs may wish to handle exceptions such as "not present segment faults" which would otherwise generate a fatal error.  Pass the following information:

AX = 0203H

BL = exception/fault number (00h - 1Fh)

CX:EDX = selector:offset of the exception handler

If the call succeeds, the carry flag is clear.  If it fails, the carry flag is set.

The address passed in CX must be a valid protected-mode selector, such as Function 204H returns, and not a real-mode segment.  A 32-bit implementation must supply a 32-bit offset in the EDX register.  If the handler chains to the next handler, it must use a 32-bit interrupt stack frame to do so.

The handler should return using a far return instruction.  The original SS:ESP, CS:EIP and flags on the stack, including the interrupt flag, will be restored.

All fault stack frames have an error code.  However the error code is only valid for exceptions 08h, 0Ah, 0Bh, 0Ch, 0Dh, and 0Eh.

The handler must preserve and restore all registers.

The exception handler will be called on a locked stack with interrupts disabled.  The original SS, ESP, CS, and EIP will be pushed on the exception handler stack frame.

The handler must either return from the call by executing a far return or jump to the next handler in the chain (which will execute a far return or chain to the next handler).

The procedure can modify any of the values on the stack pertaining to the exception before returning.  This can be used, for example, to jump to a procedure by modifying the CS:EIP on the stack.  Note that the procedure must not modify the far return address on the stack - it must return to the original caller.  The caller will then restore the flags, CS:EIP and SS:ESP from the stack frame.

If the DPMI client does not handle an exception, or jumps to the default exception handler, the host will reflect the exception as an interrupt for exceptions 0, 1, 2, 3, 4, 5 and 7.  Exceptions 6 and 8 - 1Fh will be treated as fatal errors and the client will be terminated.

Exception handlers will only be called for exceptions that occur in protected mode.

Function 0204H

This function gets the CS:EIP selector:offset of the current protected-mode interrupt handler for a specified interrupt number.  Pass the following information:

AX = 0204H

BL = interrupt number

This call always succeeds.  All 100H (256 decimal) interrupt vectors are supported by the host.  When the call returns, the carry flag is clear and CX:EDX contains the protected-mode selector:offset of the exception handler.

A 32-bit offset is returned in the EDX register.

Function 0205H

This function sets the address of the specified protected-mode interrupt vector.  Pass the following information:

AX = 0205H

BL = interrupt number

CX:EDX = selector:offset of the exception handler

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set.

The address passed in CX must be a valid protected-mode selector, such as Function 204H returns, and not a real-mode segment.  A 32-bit implementation must supply a 32-bit offset in the EDX register.  If the handler chains to the next handler, it must use a 32-bit interrupt stack frame to do so.

DOS/4GW:  Translation Services

Function 0300H

This function simulates a real-mode interrupt.  This function simulates an interrupt in real mode.  It will invoke the CS:IP specified by the real-mode interrupt vector and the handler must return by executing an iret.  Pass the following information:

AX = 0300H

BL = interrupt number

BH = flags

Bit 0 = 1 resets the interrupt controller and A20 line.  Other flags are reserved and must be 0.

CX = number of words to copy from protected-mode stack to real-mode stack

ES:EDI = the selector:offset of real-mode call structure

If the call fails, the carry flag is set.

If the call succeeds, the carry flag is clear and ES:EDI contains the selector:offset of the modified real-mode call structure.

The CS:IP in the real-mode call structure is ignored by this service.  The appropriate interrupt handler will be called based on the value passed in BL.

The flags specified in the real-mode call structure will be pushed on the real-mode stack iret frame.  The interrupt handler will be called with the interrupt and trace flags clear.

It is up to the caller to remove any parameters that were pushed on the protected-mode stack.

The flag to reset the interrupt controller and the A20 line is ignored by DPMI implementations that run in Virtual 8086 mode.  It causes DPMI implementations that return to real mode to set the interrupt controller and A20 address line hardware to its normal real-mode state.

Function 0301H

(DOS/4GW Professional only) This function calls a real-mode procedure with a FAR return frame.  The called procedure must execute a FAR return when it completes.  Pass the following information:

AX = 0301H

BH = flags

Bit 0 = 1 resets the interrupt controller and A20 line.  Other flags reserved and must be 0.

CX = Number of words to copy from protected-mode to real-mode stack

ES:EDI = selector:offset of real-mode call structure

If the call succeeds, the carry flag is clear and ES:EDI contains the selector:offset of modified real-mode call structure.

If the call fails, the carry flag is set.

Notes:

1. The CS:IP in the real-mode call structure specifies the address of the real-mode procedure to call.
2. The real-mode procedure must execute a FAR return when it has completed.
3. If the SS:SP fields are zero then a real-mode stack will be provided by the DPMI host.  Otherwise, the real-mode SS:SP will be set to the specified values before the procedure is called.
4. When the Int 31h returns, the real-mode call structure will contain the values that were returned by the real-mode procedure.
5. It is up to the caller to remove any parameters that were pushed on the protected-mode stack.
6. The flag to reset the interrupt controller and A20 line is ignored by DPMI implementations that run in Virtual 8086 mode.   It causes DPMI implementations that return to real mode to set the interrupt controller and A20 address line hardware to its normal real-mode state.

Function 0302H

(DOS/4GW Professional only) This function calls a real-mode procedure with an iret frame.  The called procedure must execute an iret when it completes.  Pass the following information:

AX = 0302H

BH = flags

Bit 0 = 1 resets the interrupt controller and A20 line.  Other flags reserved and must be 0.

CX = Number of words to copy from protected-mode to real-mode stack

ES:EDI = selector:offset of real-mode call structure

If the call succeeds, the carry flag is clear and ES:EDI contains the selector:offset of modified real-mode call structure.

If the call fails, the carry flag is set.

Notes:

1. The CS:IP in the real-mode call structure specifies the address of the real-mode procedure to call.
2. The real-mode procedure must execute an iret when it has completed.
3. If the SS:SP fields are zero then a real-mode stack will be provided by the DPMI host.  Otherwise, the real-mode SS:SP will be set to the specified values before the procedure is called.
4. When the Int 31h returns, the real-mode call structure will contain the values that were returned by the real-mode procedure.
5. The flags specified in the real-mode call structure will be pushed the real-mode stack iret frame.  The procedure will be called with the interrupt and trace flags clear.
6. It is up to the caller to remove any parameters that were pushed on the protected-mode stack.
7. The flag to reset the interrupt controller and A20 line is ignored by DPMI implementations that run in Virtual 8086 mode.   It causes DPMI implementations that return to real mode to set the interrupt controller and A20 address line hardware to its normal real-mode state.

Function 0303H

(DOS/4GW Professional only) This function allocates a real-mode callback address.  This service is used to obtain a unique real-mode SEG:OFFSET that will transfer control from real mode to a protected-mode procedure.
At times it is necessary to hook a real-mode interrupt or device callback in a protected-mode driver.  For example, many mouse drivers call an address whenever the mouse is moved.  Software running in protected mode can use a real-mode callback to intercept the mouse driver calls.  Pass the following information:

AX = 0303H

DS:ESI = selector:offset of procedure to call

ES:EDI = selector:offset of real-mode call structure

If the call succeeds, the carry flag is clear and CX:DX contains the segment:offset of real-mode callback address.

If the call fails, the carry flag is set.

Callback Procedure Parameters

     Interrupts disabled
     DS:ESI = selector:offset of real-mode SS:SP
     ES:EDI = selector:offset of real-mode call structure
     SS:ESP = Locked protected-mode API stack
     All other registers undefined

Return from Callback Procedure

     Execute an IRET to return
     ES:EDI =  selector:offset of real-mode call structure
     to restore (see note)

Notes:

1. Since the real-mode call structure is static, you must be careful when writing code that may be reentered.  The simplest method of avoiding reentrancy is to leave interrupts disabled throughout the entire call.  However, if the amount of code executed by the callback is large then you will need to copy the real-mode call structure into another buffer.  You can then return with ES:EDI pointing to the buffer you copied the data to - it does not have to point to the original real mode call structure.
2. The called procedure is responsible for modifying the real-mode CS:IP before returning.  If the real-mode CS:IP is left unchanged then the real-mode callback will be executed immediately and your procedure will be called again.  Normally you will want to pop a return address off of the real-mode stack and place it in the real-mode CS:IP.  The example code in the next section demonstrates chaining to another interrupt handler and simulating a real-mode iret.
3. To return values to the real-mode caller, you must modify the real-mode call structure.
4. Remember that all segment values in the real-mode call structure will contain real-mode segments, not selectors.  If you need to examine data pointed to by a real-mode seg:offset pointer, you should not use the segment to selector service to create a new selector.  Instead, allocate a descriptor during initialization and change the descriptor's base to 16 times the real-mode segment's value.  This is important since selectors allocated though the segment to selector service can never be freed.
5. DPMI hosts should provide a minimum of 16 callback addresses per task.

The following code is a sample of a real-mode interrupt hook.  It hooks the DOS Int 21h and returns an error for the delete file function (AH=41h).  Other calls are passed through to DOS.  This example is somewhat silly but it demonstrates the techniques used to hook a real mode interrupt.  Note that since DOS calls are reflected from protected mode to real mode, the following code will intercept all DOS calls from both real mode and protected mode.

     
     ;******************************************************
     ; This procedure gets the current Int 21h real-mode
     ; Seg:Offset, allocates a real-mode callback address,
     ; and sets the real-mode Int 21h vector to the call-
     ; back address.
     ;******************************************************
     Initialization_Code:
     ;
     ; Create a code segment alias to save data in
     ;
             mov     ax, 000Ah
             mov     bx, cs
             int     31h
             jc      ERROR
             mov     ds, ax
             ASSUMES DS,_TEXT
     ;
     ; Get current Int 21h real-mode SEG:OFFSET
     ;
             mov     ax, 0200h
             mov     bl, 21h
             int     31h
             jc      ERROR
             mov     [Orig_Real_Seg], cx
             mov     [Orig_Real_Offset], dx
     ;
     ; Allocate a real-mode callback
     ;
             mov     ax, 0303h
             push    ds
             mov     bx, cs
             mov     ds, bx
             mov     si, OFFSET My_Int_21_Hook
             pop     es
             mov     di, OFFSET My_Real_Mode_Call_Struc
             int     31h
             jc      ERROR
     ;
     ; Hook real-mode int 21h with the callback address
     ;
             mov     ax, 0201h
             mov     bl, 21h
             int     31h
             jc      ERROR

     ;******************************************************
     ;
     ; This is the actual Int 21h hook code.  It will return
     ; an "access denied" error for all calls made in real
     ; mode to delete a file.  Other calls will be passed
     ; through to DOS.
     ;
     ; ENTRY:
     ;    DS:SI -> Real-mode SS:SP
     ;    ES:DI -> Real-mode call structure
     ;    Interrupts disabled
     ;
     ; EXIT:
     ;    ES:DI -> Real-mode call structure
     ;
     ;******************************************************

     My_Int_21_Hook:
             cmp     es:[di.RealMode_AH], 41h
             jne     Chain_To_DOS
     ;
     ; This is a delete file call (AH=41h).  Simulate an
     ; iret on the real-mode stack, set the real-mode
     ; carry flag, and set the real-mode AX to 5 to indicate
     ; an access denied error.
     ;
             cld
             lodsw                    ; Get real-mode ret IP
             mov     es:[di.RealMode_IP], ax
             lodsw                    ; Get real-mode ret CS
             mov     es:[di.RealMode_CS], ax
             lodsw                    ; Get real-mode flags
             or      ax, 1            ; Set carry flag
             mov     es:[di.RealMode_Flags], ax
             add     es:[di.RealMode_SP], 6
             mov     es:[di.RealMode_AX], 5
             jmp     My_Hook_Exit
     ;
     ; Chain to original Int 21h vector by replacing the
     ; real-mode CS:IP with the original Seg:Offset.
     ;
     Chain_To_DOS:
             mov     ax, cs:[Orig_Real_Seg]
             mov     es:[di.RealMode_CS], ax
             mov     ax, cs:[Orig_Real_Offset]
             mov     es:[di.RealMode_IP], ax

     My_Hook_Exit:
             iret

Function 0304H

(DOS/4GW Professional only) This function frees a real-mode callback address that was allocated through the allocate real-mode callback address service.  Pass the following information:

AX = 0304H

CX:DX = Real-mode callback address to free

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set.

Notes:

1. Real-mode callbacks are a limited resource.  Your code should free any break point that it is no longer using.

DOS/4GW:  DPMI Version

Function 0400H

This function returns the version of DPMI services supported.  Note that this is not necessarily the version of any operating system that supports DPMI.  It should be used by programs to determine what calls are legal in the current environment.   Pass the following information:

AX = 0400H

The information returned is:

AH = Major version

AL = Minor version

BX = Flags

Bit 0 = 1 if running under an 80386 DPMI implementation.  Bit 1 = 1 if processor is returned to real mode for reflected interrupts (as opposed to Virtual 8086 mode).  Bit 2 = 1 if virtual memory is supported.  Bit 3 is reserved and undefined.  All other bits are zero and reserved for later use.

CL = Processor type

     02 = 80286
     03 = 80386
     04 = 80486
     05 = Pentium

DH = Current value of virtual master PIC base interrupt

DL = Current value of virtual slave PIC base interrupt

Carry flag clear (call cannot fail)

DOS/4GW:  Memory Management Services

Function 0500H

This function gets information about free memory.  Pass the following information:

AX = 0500H

ES:EDI = the selector:offset of a 30H byte buffer.

If the call fails, the carry flag is set.

If the call succeeds, the carry flag is clear and ES:EDI contains the selector:offset of a buffer with the structure shown in the figure below.

            Offset  Description                            

            00H     Largest available block, in bytes    

            04H     Maximum unlocked page allocation     

            08H     Largest block of memory (in pages) that
could                                                      
                    be allocated and then locked         

            0CH     Total linear address space size, in pages,
including                                                  
                    already allocated pages              

            10H     Total number of free pages and pages 
currently                                                  
                    unlocked and available for paging out

            14H     Number of physical pages not in use  

            18H     Total number of physical pages managed by host

            1CH     Free linear address space, in pages  

            20H     Size of paging/file partition, in pages

            24H -   Reserved                               
            2FH                                            

Only the first field of the structure is guaranteed to contain a valid value.  Any field that is not returned by DOS/4GW is set to -1 (0FFFFFFFFH).

Function 0501H

This function allocates and commits linear memory.  Pass the following information:

AX = 0501H

BX:CX = size of memory to allocate, in bytes.

If the call succeeds, the carry flag is clear, BX:CX contains the linear address of the allocated memory, and SI:DI contains the memory block handle used to free or resize the block.  If the call fails, the carry flag is set.

No selectors are allocated for the memory block.  The caller must allocate and initialize selectors needed to access the memory.

If VMM is present, the memory is allocated as unlocked, page granular blocks.  Because of the page granularity, memory should be allocated in multiples of 4KB.

Function 0502H

This function frees a block of memory allocated through function 0501H.  Pass the following information:

AX = 0502H

SI:DI = handle returned with function 0501H when memory was allocated

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set.  You must also free any selectors allocated to point to the freed memory block.

Function 0503H

This function resizes a block of memory allocated through the 0501H function.  If you resize a block of linear memory, it may have a new linear address and a new handle.  Pass the following information:

AX = 0503H

BX:CX = new size of memory block, in bytes

SI:DI = handle returned with function 0501H when memory was allocated

If the call succeeds, the carry flag is clear, BX:CX contains the new linear address of the memory block, and SI:DI contains the new handle of the memory block.  If the call fails, the carry flag is set.

If either the linear address or the handle has changed, update the selectors that point to the memory block.  Use the new handle instead of the old one.

You cannot resize a memory block to zero bytes.

DOS/4GW:  Page Locking Services

Function 0600H

This function locks a specified linear address range.  Pass the following information:

AX = 0600H

BX:CX = starting linear address of memory to lock

SI:DI = size of region to lock (in bytes)

If the call fails, the carry flag is set and none of the memory will be locked.

If the call succeeds, the carry flag is clear.  If the specified region overlaps part of a page at the beginning or end of a region, the page(s) will be locked.

Function 0601H

This function unlocks a specified linear address range that was previously locked using the "lock linear region" function (0600h).  Pass the following information:

AX = 0601H

BX:CX = starting linear address of memory to unlock

SI:DI = size of region to unlock (in bytes)

If the call fails, the carry flag is set and none of the memory will be unlocked.  An error will be returned if the memory was not previously locked or if the specified region is invalid.

If the call succeeds, the carry flag is clear.  If the specified region overlaps part of a page at the beginning or end of a region, the page(s) will be unlocked.  Even if the call succeeds, the memory will remain locked if the lock count is not decremented to zero.

Function 0604H

This function gets the page size for Virtual Memory (VM) only.  This function returns the size of a single memory page in bytes.  Pass the following information:

AX = 0604H

If the call succeeds, the carry flag is clear and BX:CX = Page size in bytes.

If the call fails, the carry flag is set.

DOS/4GW:  Demand Paging Performance Tuning Services

Function 0702H

(DOS/4GW Professional only) This function marks a page as a demand paging candidate.  This function is used to inform the operating system that a range of pages should be placed at the head of the page out candidate list.  This will force these pages to be swapped to disk ahead of other pages even if the memory has been accessed recently.  However, all memory contents will be preserved.
This is useful, for example, if a program knows that a given piece of data will not be accessed for a long period of time.   That data is ideal for swapping to disk since the physical memory it now occupies can be used for other purposes.  Pass the following information:

AX = 0702H

BX:CX = Starting linear address of pages to mark

SI:DI = Number of bytes to mark as paging candidates

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set.

Notes:

1. This function does not force the pages to be swapped to disk immediately.
2. Partial pages will not be discarded.

Function 0703H

(DOS/4GW Professional only) This function discards page contents.  This function discards the entire contents of a given linear memory range.  It is used after a memory object that occupied a given piece of memory has been discarded.
The contents of the region will be undefined the next time the memory is accessed.  All values previously stored in this memory will be lost.  Pass the following information:

AX = 0703H

BX:CX = Starting linear address of pages to discard

SI:DI = Number of bytes to discard

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set.

Notes:

1. Partial pages will not be discarded.

DOS/4GW:  Physical Address Mapping

Function 0800H

This function is used for Physical Address Mapping.
Some implementations of DPMI may not support this call because it could be used to circumvent system protection.  This call should only be used by programs that absolutely require direct access to a memory mapped device.

Pass the following information:

AX = 0800H

BX:CX = Physical address of memory

SI:DI = Size of region to map in bytes

If the call succeeds, the carry flag is clear and BX:CX = Linear Address that can be used to access the physical memory.

If the call fails, the carry flag is set.

Notes:

1. Under DPMI implementations that do not use the 80386 paging mechanism, the call will always succeed and the address returned will be equal to the physical address parameter passed into this function.
2. It is up to the caller to build an appropriate selector to access the memory.
3. Do not use this service to access memory that is mapped in the first megabyte of address space (the real-mode addressable region).

Function 0801H

This function is used to free Physical Address Mapping.  Pass the following information:

AX = 0801H

BX:CX = Linear address returned by Function 0800H.

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set.

Notes:

1. The client should call this function when it is finished using a device previously mapped to linear addresses with the Physical Address Mapping function (Function 0800H).

DOS/4GW:  Virtual Interrupt State Functions

Function 0900H

This function gets and disables Virtual Interrupt State.  This function will disable the virtual interrupt flag and return the previous state of the virtual interrupt flag.  Pass the following information:

AX = 0900H

After the call, the carry flag is clear (this function always succeeds) and virtual interrupts are disabled.

     AL = 0 if virtual interrupts were previously disabled.
     AL = 1 if virtual interrupts were previously enabled.

Notes:

1. AH will not be changed by this procedure.  Therefore, to restore the previous state, simply execute an Int 31h.

Function 0901H

This function gets and enables the Virtual Interrupt State.  This function will enable the virtual interrupt flag and return the previous state of the virtual interrupt flag.  Pass the following information:

AX = 0901H

After the call, the carry flag is clear (this function always succeeds) and virtual interrupts are enabled.

     AL = 0 if virtual interrupts were previously disabled.
     AL = 1 if virtual interrupts were previously enabled.

Notes:

1. AH will not be changed by this procedure.  Therefore, to restore the previous state, simply execute an Int 31h.

Function 0902H

This function gets the Virtual Interrupt State.  This function will return the current state of the virtual interrupt flag.  Pass the following information:

AX = 0902H

After the call, the carry flag is clear (this function always succeeds).

     AL = 0 if virtual interrupts are disabled.
     AL = 1 if virtual interrupts are enabled.

DOS/4GW:  Vendor Specific Extensions

Function 0A00H

This function gets Tenberry Software's API Entry Point.  Pass the following information:

AX = 0A00H

DS:ESI = Pointer to null terminated string "RATIONAL DOS/4G"

If the call succeeds, the carry flag is clear and ES:EDI = Extended API entry point.  DS, FS, GS, EAX, EBX, ECX, EDX, ESI, and EBP may be modified.

If the call fails, the carry flag is set.

Notes:

1. Execute a far call to call the API entry point.
2. All extended API parameters are specified by the vendor.
3. The string comparison used to return the API entry point is case sensitive.

DOS/4GW:  Coprocessor Status

Function 0E00H

This function gets the coprocessor status.  Pass the following information:

AX = 0E00H

If the call succeeds, the carry flag is clear and AX contains the coprocessor status.

Bit

Significance

0

MPv (MP bit in the virtual MSW/CR0).
0 = Numeric coprocessor is disabled for this client.
1 = Numeric coprocessor is disabled for this client.

1

EMv (EM bit in the virtual MSW/CR0).
0 = Client is not emulating coprocessor instructions.
1 = Client is emulating coprocessor instructions.

2

MPr (MP bit from the actual MSW/CR0).
0 = Numeric coprocessor is not present.
1 = Numeric coprocessor is present.

1

EMr (EM bit from the actual MSW/CR0).
0 = Host is not emulating coprocessor instructions.
1 = Host is emulating coprocessor instructions.

4-7

Coprocessor type.
     00H = no coprocessor.
     02H = 80287
     03H = 80387
     04H = 80486 with numeric coprocessor
     05H = Pentium

8-15

Not applicable.

If the call fails, the carry flag is set.

Notes:

1. If the real EM (EMr) bit is set, the host is supplying or is capable of supplying floating-point emulation.
2. If the MPv bit is not set, the host may not need to save the coprocessor state for this virtual machine to improve system performance.
3. The MPr bit setting should be consistent with the setting of the coprocessor type information.  Ignore MPr bit information if it is in conflict with the coprocessor type information.
4. If the virtual EM (EMv) bit is set, the host delivers all coprocessor exceptions to the client, and the client is performing its own floating-point emulation (wether or not a coprocessor is present or the host also has a floating-point emulator).   In other words, if the EMv bit is set, the host sets the EM bit in the real CR0 while the virtual machine is active, and reflects coprocessor not present faults (int 7) to the virtual machine.
5. A client can determine the CPU type with int 31H Function 0400H, but a client should not draw any conclusions about the presence or absence of a coprocessor based on the CPU type alone.

Function 0E01H

This function sets coprocessor emulation.  Pass the following information:

AX = 0E01H

BX = coprocessor bits

Bit

Significance

0

New value of MPv bit for client's virtual CR0.
0 = Disable numeric coprocessor for this client.
1 = Enable numeric coprocessor for this client.

1

New value of EMv bit for client's virtual CR0.
0 = client will not supply coprocessor emulation.
1 = client will supply coprocessor emulation.

2-15

Not applicable.

If the call succeeds, the carry flag is clear; if it fails, the carry flag is set.

DOS/4GW:  Utilities

Purpose:

This is a brief statement of what the utility program does.  More specific information is provided under "Notes".

Syntax:

This shows the syntax of the program.  The fixed portion of each command is in a typewriter font, while variable parts of the command are in italics.  Optional parts are enclosed in [brackets].

Notes:

These are explanatory remarks noting major features and possible pitfalls.  We explain anything special that you might need to know about the program.

See Also:

This is a cross-reference to any information that is related to the program.

Example:

You'll find one or more sample uses of the utility program with an explanation of what the program is doing.

DOS/4GW:  DOS4GW

Purpose:

Loads and executes linear executables.

Syntax:

linear_executable

Notes:

The stub program at the beginning of the linear executable invokes this program, which loads the linear executable and starts up the DOS extender.  The stub program must be able to find DOS4GW:  make sure it is in the path.

DOS/4GW:  PMINFO

Purpose:

Measures the performance of protected/real-mode switching and extended memory.

Syntax:

PMINFO.EXE

Notes:

We encourage you to distribute this program to your users.
The time-based measurements made by PMINFO may vary slightly from run to run.

Example:

The following example shows the output of the PMINFO program on a 386 AT-compatible machine.

---

   C>pminfo
        Protected Mode and Extended Memory Performance Measurement -- 5.00
                Copyright (c) Tenberry Software, Inc. 1987 - 1993

   DOS memory   Extended memory   CPU performance equivalent to 67.0 MHz 80486
   ----------   ---------------
          736               8012   K bytes configured (according to BIOS).
          640              15360   K bytes physically present (SETUP).
          651               7887   K bytes available for DOS/16M programs.
   22.0 (3.0)        18.9 (4.0)   MB/sec word transfer rate (wait states).
   42.9 (3.0)        37.0 (4.0)   MB/sec 32-bit transfer rate (wait states).

   Overall cpu and memory performance (non-floating point) for typical
   DOS programs is 10.36 ñ 1.04 times an 8MHz IBM PC/AT.

   Protected/Real switch rate = 36156/sec (27 usec/switch, 15 up + 11 down),
   DOS/16M switch mode 11 (VCPI).

---

The top information line shows that the CPU performance is equivalent to a 67.0 MHz 80486.  Below are the configuration and timings for both the DOS memory and extended memory.  If the computer is not equipped with extended memory, or none is available for DOS/4GW, the extended memory measurements may be omitted ("--").

The line "according to BIOS" shows the information provided by the BIOS (interrupts 12h and 15h function 88h).  The line "SETUP", if displayed, is the configuration obtained directly from the CMOS RAM as set by the computer's setup program.  It is displayed only if the numbers are different from those in the BIOS line.  They will be different for computers where the BIOS has reserved memory for itself or if another program has allocated some memory and is intercepting the BIOS configuration requests to report less memory available than is physically configured.   The "DOS/16M memory range", if displayed, shows the low and high addresses available to DOS/4GW in extended memory.

Below the configuration information is information on the memory speed (transfer rate).  PMINFO tries to determine the memory architecture.  Some architectures will perform well under some circumstances and poorly under others; PMINFO will show both the best and worst cases.  The architectures detected are cache, interleaved, page-mode (or static column), and direct.  Measurements are made using 32-bit accesses and reported as the number of megabytes per second that can be transferred.  The number of wait states is reported in parentheses.  The wait states can be a fractional number, like 0.5, if there is a wait state on writes but not on reads.  Memory bandwidth (i.e., how fast the CPU can access memory) accounts for 60% to 70% of the performance for typical programs (that are not heavily dependent on floating-point math).

A performance metric developed by Tenberry Software is displayed, showing the expected throughput for the computer relative to a standard 8MHz IBM PC/AT (disk accesses and floating point are excluded).  Finally, the speed with which the computer can switch between real and protected mode is displayed, both as the maximum number of round-trip switches that can occur per second, and the time for a single round-trip switch, broken out into the real-to-protected (up) and protected-to-real (down) components.

DOS/4GW:  PRIVATXM

Purpose:

Creates a private pool of memory for DOS/4GW programs.

Syntax:

PRIVATXM [-r]

Notes:

This program may be distributed to your users.
Without PRIVATXM, a DOS/4GW program that starts up while another DOS/4GW program is active uses the pool of memory built by the first program.  The new program cannot change the parameters of this memory pool, so setting DOS16M to increase the size of the pool has no effect.  To specify that the two programs use different pools of memory, use PRIVATXM.

PRIVATXM marks the active DOS/4GW programs as private, preventing subsequent DOS/4GW programs from using the same memory pool.  The first DOS/4GW program to start after PRIVATXM sets up a new pool of memory for itself and any subsequent DOS/4GW programs.  To release the memory used by the private programs, use the PRIVATXM -r option.

PRIVATXM is a TSR that requires less than 500 bytes of memory.  It is not supported under DPMI.

Example:

The following example creates a 512KB memory pool that is shared by two DOS/4GW TSRs.  Subsequent DOS/4GW programs use a different memory pool.

C>set DOS16M= :512

Specifies the size of the memory pool.

C>TSR1

Sets up the memory pool at startup.

C>TSR2

This TSR shares the pool built by TSR1.

C>PRIVATXM

Makes subsequent DOS/4GW programs use a new memory pool.

C>set DOS16M=

Specifies an unlimited size for the new pool.

C>PROGRAM3

This program uses the new memory pool.

C>PRIVATXM -R

Releases the 512KB memory pool used by the TSRs.  (If the TSRs shut down, their memory is not released unless PRIVATXM is released.)

DOS/4GW:  RMINFO

Purpose:

Supplies configuration information and the basis for real/protected-mode switching in your machine.

Syntax:

RMINFO.EXE

Notes:

This program may be distributed to your users.
RMINFO starts up DOS/4GW, but stops your machine just short of switching from real mode to protected mode and displays configuration information about your computer.  The information shown by RMINFO can help determine why DOS/4GW applications won't run on a particular machine.  Run RMINFO if PMINFO does not run to completion.

Example:

The following example shows the output of the RMINFO program on an 386 AT-compatible machine.

---

   C>rminfo

   DOS/16M Real Mode Information Program 5.00
   Copyright (C) Tenberry Software, Inc. 1987 - 1993

   Machine and Environment:
           Processor:               i386, coprocessor present
           Machine type:            10 (AT-compatible)
           A20 now:                 enabled
           A20 switch rigor:       disabled
           DPMI host found
   Switching Functions:
           To PM switch:            DPMI
           To RM switch:            DPMI
           Nominal switch mode:    0
           Switch control flags:   0000
   Memory Interfaces:
           DPMI may provide:       16384K returnable
           Contiguous DOS memory:  463K

---

The information provided by RMINFO includes:

Machine and Environment:

Processor:

processor type, coprocessor present/not present

Machine type:

     (NEC 9801)
     (PS/2-compatible)
     (AT-compatible)
     (FM R)
     (AT&T 6300+)
     (AT-compatible)
     (C&T 230 chipset)
     (AT-compatible)
     (AT-compatible)
     (Acer)
     (Zenith)
     (Hitachi)
     (Okidata)
     (PS/55)

A20 now:

Current state of Address line 20.

A20 switch rigor:

Whether DOS4GW rigorously controls enabling and disabling of Address line 20 when switching modes.

PS feature flag

XMS host found

Whether your system has any software using extended memory under the XMS discipline.

VCPI host found

Whether your system has any software using extended memory under the VCPI discipline.

page table 0 at:  x000h

DPMI host found

DOS/16M resident with private/public memory

Switching Functions:

A20 switching:

To PM switch:

reset catch:
pre-PM prep:
post-PM-switch:

To RM switch:

pre-RM prep:
reset method:
post-reset:
reset uncatch:

Nominal switch mode:  x

Switch control flags:  xxxxh

Memory Interfaces:

(VCPI remapping in effect)

DPMI may provide:  xxxxxK returnable

VCPI may provide:  xxxxxK returnable

Top-down

Other16M

Forced

Contiguous DOS memory:

DOS/4GW:  Error Messages

DOS/4GW:  Kernel Error Messages

0.  involuntary switch to real mode

The computer was in protected mode but switched to real mode without going through DOS/16M.  This error most often occurs because of an unrecoverable stack segment exception (stack overflow), but can also occur if the Global Descriptor Table or Interrupt Descriptor Table is corrupted.  Increase the stack size, recompile your program with stack overflow checking, or look into ways that the descriptor tables may have been overwritten.

1.  not enough extended memory

2.  not a DOS/16M executable <filename>

DOS4G.EXE, or a bound DOS/4G application, has probably been corrupted in some way.  Rebuild or recopy the file.

3.  no DOS memory for transparent segment

4.  cannot make transparent segment

5.  too many transparent segments

6.  not enough memory to load program

There is not enough memory to load DOS/4G.  Make more memory available and try again.

7.  no relocation segment

8.  cannot open file <filename>

The DOS/16M loader cannot load DOS/4G, probably because DOS has run out of file units.  Set a larger FILES= entry in CONFIG.SYS, reboot, and try again.

9.  cannot allocate tstack

There is not enough memory to load DOS/4G.  Make more memory available and try again.

10.  cannot allocate memory for GDT

There is not enough memory to load DOS/4G.  Make more memory available and try again.

11.  no passup stack selectors -- GDT too small

This error indicates an internal error in DOS/4G or an incompatibility with other software.

12.  no control program selectors -- GDT too small

This error indicates an internal error in DOS/4G or an incompatibility with other software.

13.  cannot allocate transfer buffer

There is not enough memory to load DOS/4G.  Make more memory available and try again.

14.  premature EOF

DOS4G.EXE, or a bound DOS/4G application, has probably been corrupted in some way.  Rebuild or recopy the file.

15.  protected mode available only with 386 or 486

DOS/4G requires an 80386 (or later) CPU.  It cannot run on an 80286 or earlier CPU.

16.  cannot run under OS/2

17.  system software does not follow VCPI or DPMI specifications

Some memory resident program has put your 386 or 486 CPU into Virtual 8086 mode.  This is done to provide special memory services to DOS programs, such as EMS simulation (EMS interface without EMS hardware) or high memory.  In this mode, it is not possible to switch into protected mode unless the resident software follows a standard that DOS/16M supports (DPMI, VCPI, and XMS are the most common).  Contact the vendor of your memory management software.

18.  you must specify an extended memory range (SET DOS16M= )

On some Japanese machines that are not IBM AT-compatible, and have no protocol for managing extended memory, you must set the DOS16M environment variable to specify the range of available extended memory.

19.  computer must be AT- or PS/2- compatible

20.  unsupported DOS16M switchmode choice

21.  requires DOS 3.0 or later

22.  cannot free memory

This error probably indicates that memory was corrupted during execution of your program.

23.  no memory for VCPI page table

There is not enough memory to load DOS/4G.  Make more memory available and try again.

24.  VCPI page table address incorrect

This is an internal error.

25.  cannot initialize VCPI

This error indicates an incompatibility with other software.  DOS/16M has detected that VCPI is present, but VCPI returns an error when DOS/16M tries to initialize the interface.

26.  8042 timeout

27.  extended memory is configured but it cannot be allocated

28.  memory error, avail loop

This error probably indicates that memory was corrupted during execution of your program.  Using an invalid or stale alias selector may cause this error.  Incorrect manipulation of segment descriptors may also cause it.

29.  memory error, out of range

This error probably indicates that memory was corrupted during execution of your program.  Writing through an invalid or stale alias selector may cause this error.

30.  program must be built -AUTO for DPMI

31.  protected mode already in use in this DPMI virtual machine

32.  DPMI host error (possibly insufficient memory)

33.  DPMI host error (need 64K XMS)

34.  DPMI host error (cannot lock stack)

Any of these errors (32, 33, 34) probably indicate insufficient memory under DPMI.  Under Windows, you might try making more physical memory available by eliminating or reducing any RAM drives or disk caches.  You might also try editing DEFAULT.PIF so that at least 64KB of XMS memory is available to non-Windows programs.  Under OS/2, you want to increase the DPMI_MEMORY_LIMIT in the DOS box settings.

35.  General Protection Fault

This message probably indicates an internal error in DOS/4G.  Faults generated by your program should cause error 2001 instead.

36.  The DOS16M.386 virtual device driver was never loaded

37.  Unable to reserve selectors for DOS16M.386 Windows driver

38.  Cannot use extended memory:  HIMEM.SYS not version 2

This error indicates an incompatibility with an old version of HIMEM.SYS.

39.  An obsolete version of DOS16M.386 was loaded

40.  not enough available extended memory (XMIN)

This message probably indicates an incompatibility with your memory manager or its configuration.  Try configuring the memory manager to provide more extended memory, or change memory managers.

DOS/4GW:  DOS/4G Errors

1000 "can't hook interrupts"

A DPMI host has prevented DOS/4G from loading.  Please contact Tenberry Technical Support.

1001 "error in interrupt chain"

DOS/4G internal error.  Please contact Tenberry Technical Support.

1003 "can't lock extender kernel in memory"

DOS/4G couldn't lock the kernel in physical memory, probably because of a memory shortage.

1004 "syntax is DOS4G <executable.xxx>"

You must specify a program name.

1005 "not enough memory for dispatcher data"

There is not enough memory for DOS/4G to manage user-installed interrupt handlers properly.  Free some memory for the DOS/4G application.

1007 "can't find file <program> to load"

DOS/4G could not open the specified program.  Probably the file didn't exist.  It is possible that DOS ran out of file handles, or that a network or similar utility has prohibited read access to the program.  Make sure that the file name was spelled correctly.

1008 "can't load executable format for file <filename> [<error code>]"

DOS/4G did not recognize the specified file as a valid executable file.  DOS/4G can load linear executables (LE and LX) and EXPs (BW).  The error code is for Tenberry Software's use.

1009 "program <filename> is not bound"

This message does not occur in DOS/4G, only DOS/4GW Professional; the latter requires that the DOS extender be bound to the program file.  The error signals an attempt to load

1010 "can't initialize loader <loader> [<error code>]"

DOS/4G could not initialize the named loader, probably because of a resource shortage.  Try making more memory available.   If that doesn't work, please contact Tenberry Technical Support.  The error code is for Tenberry Software' use.

1011 "VMM initialization error [<error code>]"

DOS/4G could not initialize the Virtual Memory Manager, probably because of a resource shortage.  Try making more memory available.  If that doesn't work, please contact Tenberry Technical Support.  The error code is for Tenberry Software' use.

1012 "<filename> is not a WATCOM program"

This message does not occur in DOS/4G, only DOS/4GW and DOS/4GW Professional.  Those extenders only support WATCOM 32-bit compilers.

1013 "int 31h initialization error"

DOS/4G was unable to initialize the code that handles Interrupt 31h, probably because of an internal error.  Please call Tenberry Technical Support.

1100 "assertion \"<statement>\" failed (<file>:<line>)"

DOS/4G internal error.  Please contact Tenberry Technical Support.

1200 "invalid EXP executable format"

DOS/4G tried to load an EXP, but couldn't.  The executable file is probably corrupted.

1201 "program must be built -AUTO for DPMI"

Under DPMI, DOS/4G can only load EXPs that have been linked with the GLU -AUTO or -DPMI switch.

1202 "can't allocate memory for GDT"

There is not enough memory available for DOS/4G to build a Global Descriptor Table.  Make more memory available.

1203 "premature EOF"

DOS/4G tried to load an EXP but couldn't.  The file is probably corrupted.

1204 "not enough memory to load program"

There is not enough memory available for DOS/4G to load your program.  Make more memory available.

1301 "invalid linear executable format"

DOS/4G cannot recognize the program file as a LINEXE format.  Make sure that you specified the correct file name.

1304 "file I/O seek error"

DOS/4G was unable to seek to a file location that should exist.  This usually indicates truncated program files or problems with the storage device from which your program loads.  Run CHKDSK or a similar utility to begin determining possible causes.

1305 "file I/O read error"

DOS/4G was unable to read a file location that should contain program data.  This usually indicates truncated program files or problems with the storage device from which your program loads.  Run CHKDSK or a similar utility to begin determining possible causes.

1307 "not enough memory"

As it attempted to load your program, DOS/4G ran out of memory.  Make more memory available, or enable VMM.

1308 "can't load requested program"

1309 "can't load requested program"

1311 "can't load requested program"

1312 "can't load requested program"

DOS/4G cannot load your program for some reason.  Contact Tenberry Technical Support.

1313 "can't resolve external references"

DOS/4G was unable to resolve all references to DLLs for the requested program, or the program contained unsupported fixup types.  Use EXEHDR or a similar LINEXE dump utility to see what references your program makes and what special fixup records might be present.

1314 "not enough lockable memory"

As it attempted to load your program, DOS/4G encountered a refusal to lock a virtual memory region.  Some memory must be locked in order to handle demand-load page faults.  Make more physical memory available.

1315 "can't load requested program"

1316 "can't load requested program"

DOS/4G cannot load your program for some reason.  Contact Tenberry Technical Support.

1317 "program has no stack"

DOS/4G reports this error when you try to run a program with no stack.  Rebuild your program, building in a stack.

2000 "deinitializing twice"

DOS/4G internal error.  Please contact Tenberry Technical Support.

2001 "exception <exception_number> (<exception_description>) at

<selector:offset>"
Your program has generated an exception.  For information about interpreting this message, see the file COMMON.DOC.

2002 "transfer stack overflow at <selector:offset>"

Your program has overflowed the DOS/4G transfer stack.  For information about interpreting this message, see the file COMMON.DOC.

2300 " can't find <DLL>.<ordinal> - referenced from <module>"

DOS/4G could not find the ordinal listed in the specified DLL, or it could not find the DLL at all.  Correct or remove the reference, and make sure that DOS/4G can find the DLL.

DOS/4G looks for DLLs in the following directories:

• The directory specified by the Libpath32 configuration option (which defaults to the directory of the main application file).
• The directory or directories specified by the LIBPATH32 environment variable.
• Directories specified in the PATH.

2301 "can't find <DLL>.<name> - referenced from <module>"

DOS/4G could not find the entry point named in the specified module.  Correct or remove the reference, and make sure that DOS/4G can find the DLL.

2302 "DLL modules not supported"

This DOS/4GW Professional error message arises when an application references or tries to explicitly load a DLL.  DOS/4GW Professional does not support DLLs.

2303 "internal LINEXE object limit reached"

DOS/4G currently handles a maximum of 128 LINEXE objects, including all .DLL and .EXE files.  Most .EXE or .DLL files use only three or four objects.  If possible, reduce the number of objects, or contact Tenberry Technical Support.

2500 "can't connect to extender kernel"

DOS/4G internal error.  Please contact Tenberry Technical Support.

2503 "not enough disk space for swapping - <count> byes required"

VMM was unable to create a swap file of the required size.  Increase the amount of disk space available.

2504 "can't create swap file \<filename>\""

VMM was unable to create the swap file.  This could be because the swap file is specified for a nonexistent drive or on a drive that is read-only.  Set the SWAPNAME parameter to change the location of the swap file.

2505 "not enough memory for <table>"

VMM was unable to get sufficient extended memory for internal tables.  Make more memory available.  If <table> is page buffer, make more DOS memory available.

2506 "not enough physical memory (minmem)"

There is less physical memory available than the amount specified by the MINMEM parameter.  Make more memory available.

2511 "swap out error [<error code>]"

Unknown disk error.  The error code is for Tenberry Software' use.

2512 "swap in error [<error code>]"

Unknown disk error.  The error code is for Tenberry Software' use.

2514 "can't open trace file"

VMM could not open the VMM.TRC file in the current directory for writing.  If the directory already has a VMM.TRC file, delete it.  If not, there may not be enough memory on the drive for the trace file, or DOS may not have any more file handles.

2520 "can't hook int 31h"

DOS/4G internal error.  Please contact Tenberry Technical Support.

2523 "page fault on non-present mapped page"

Your program references memory that has been mapped to a nonexistent physical device, using DPMI function 508h.  Make sure the device is present, or remove the reference.

2524 "page fault on uncommitted page"

Your program references memory reserved with a call to DPMI function

504h, but never committed (using a DPMI 507h or 508h call).  Commit

the memory before you reference it.

3301 "unhandled EMPTYFWD, GATE16, or unknown relocation"

3302 "unhandled ALIAS16 reference to unaliased object"

3304 "unhandled or unknown relocation"

If your program was built for another platform that supports the LINEXE format, it may contain a construct that DOS/4G does not currently support, such as a call gate.  This message may also occur if your program has a problem mixing 16- and 32-bit code.  A linker error is another likely cause.

DOS/4GW:  DOS/4GW Commonly Asked Questions

• Access to technical support
• Differences within the DOS/4G product line
• Addressing
• Interrupt and exception handling
• Memory management
• DOS, BIOS, and mouse services
• Virtual memory
• Debugging
• Compatibility

DOS/4GW:  Access to Technical Support

1a.  How to reach technical support.

Here are the various ways you may contact Tenberry Software for technical support.

     
     WWW:    http://www.tenberry.com/dos4g/
     Email:  4gwhelp@tenberry.com
     Phone:  1.480.767.8868
     Fax:    1.480.767.8709
     Mail:   Tenberry Software, Inc.
             PO Box 20050
             Fountain Hills, Arizona
             U.S.A  85269-0050

PLEASE GIVE YOUR SERIAL NUMBER WHEN YOU CONTACT TENBERRY.

1b.  When to contact Open Watcom, when to contact Tenberry.

Since DOS/4GW Professional is intended to be completely compatible with DOS/4GW, you may wish to ascertain whether your program works properly under DOS/4GW before contacting Tenberry Software for technical support.  (This is likely to be the second question we ask you, after your serial number.)

If your program fails under both DOS/4GW and DOS/4GW Professional, and you suspect your own code or a problem compiling or linking, you may wish to contact Open Watcom first.  Tenberry Software support personnel are not able to help you with most programming questions, or questions about using the Open Watcom tools.

If your program only fails with DOS/4GW Professional, you have probably found a bug in DOS/4GW Professional, so please contact us right away.

1c.  Telephone support.

Tenberry Software's hours for telephone support are 9am-6pm EST.  Please note that telephone support is free for the first 30 days only.  A one-year contract for continuing telephone support on DOS/4GW Professional is US$500 per developer, including an update subscription for one year, to customers in the United States and Canada; for overseas customers, the price is $600.  Site licenses may be negotiated.

There is no time limit on free support by fax, mail, or electronic means.

1d.  References.

The DOS/4GW documentation from Open Watcom is the primary reference for DOS/4GW Professional as well.  Another useful reference is the DPMI specification.  In the past, the DPMI specification could be obtained free of charge by contacting Intel Literature.  We have been advised that the DPMI specification is no longer available in printed form.

However, the DPMI 1.0 specification can be obtained at:

     
     http://www.delorie.com/djgpp/doc/dpmi/

Online HTML as well as a downloadable archive are provided.

DOS/4GW:  Differences Within the DOS/4G Product Line

2a.  DOS/4GW Professional versus DOS/4GW

DOS/4GW Professional was designed to be a higher-performance version of DOS/4GW suitable for commercial applications.   Here is a summary of the advantages of DOS/4GW Professional with respect to DOS/4GW:

• Extender binds to the application program file
• Extender startup time has been reduced
• Support for Open Watcom floating-point emulator has been optimized
• Virtual memory manager performance has been greatly improved
• Under VMM, programs are demand loaded
• Virtual address space is 4 GB instead of 32 MB
• Extender memory requirements have been reduced by more than 50K
• Extender disk space requirements have been reduced by 40K
• Can omit virtual memory manager to save 50K more disk space
• Support for INT 31h functions 301h-304h and 702h-703h

DOS/4GW Professional is intended to be fully compatible with programs written for DOS/4GW 1.9 and up.  The only functional difference is that the extender is bound to your program instead of residing in a separate file.  Not only does this help reduce startup time, but it eliminates version-control problems when someone has both DOS/4GW and DOS/4GW Professional applications present on one machine.

2b.  DOS/4GW Professional versus DOS/4G.

DOS/4GW Professional is not intended to provide any other new DOS extender functionality.  Tenberry Software's top-of-the-line 32-bit extender, DOS/4G, is not sold on a retail basis but is of special interest to developers who require more flexibility (such as OEMs).  DOS/4G offers these additional features beyond DOS/4GW and DOS/4GW Professional:

• Complete documentation
• DLL support
• TSR support
• Support for INT 31h functions 301h-306h, 504h-50Ah, 702h-703h
• A C language API that offers more control over interrupt handling and program loading, as well as making it easier to use the extender
• An optional (more protected) nonzero-based flat memory model
• Remappable error messages
• More configuration options
• The D32 debugger, GLU linker, and other tools
• Support for other compilers besides Open Watcom
• A higher level of technical support
• Custom work is available (e.g., support for additional executable formats, operating system API emulations, mixed 16-bit and 32-bit code)

Please contact Tenberry Software if you have questions about other products (present or future) in the DOS/4G line.

2c.  DPMI functions supported by DOS/4GW.

Note that when a DOS/4GW application runs under a DPMI host, such as Windows 3.1 in enhanced mode, an OS/2 virtual DOS machine, 386Max (with DEBUG=DPMIXCOPY), or QDPMI (with EXTCHKOFF), the DPMI host provides the DPMI services, not DOS/4GW.   The DPMI host also provides virtual memory, if any.  Performance (speed and memory use) under different DPMI hosts varies greatly due to the quality of the DPMI implementation.

These are the services provided by DOS/4GW and DOS/4GW Professional in the absence of a DPMI host.

0000

Allocate LDT Descriptors

0001

Free LDT Descriptor

0002

Map Real-Mode Segment to Descriptor

0003

Get Selector Increment Value

0006

Get Segment Base Address

0007

Set Segment Base Address

0008

Set Segment Limit

0009

Set Descriptor Access Rights

000A

Create Alias Descriptor

000B

Get Descriptor

000C

Set Descriptor

000D

Allocate Specific LDT Descriptor

0100

Allocate DOS Memory Block

0101

Free DOS Memory Block

0102

Resize DOS Memory Block

0200

Get Real-Mode Interrupt Vector

0201

Set Real-Mode Interrupt Vector

0202

Get Processor Exception Handler

0203

Set Processor Exception Handler

0204

Get Protected-Mode Interrupt Vector

0205

Set Protected-Mode Interrupt Vector

0300

Simulate Real-Mode Interrupt

0301

Call Real-Mode Procedure with Far Return Frame (DOS/4GW Professional only)

0302

Call Real-Mode Procedure with IRET Frame (DOS/4GW Professional only)

0303

Allocate Real-Mode Callback Address (DOS/4GW Professional only)

0304

Free Real-Mode Callback Address (DOS/4GW Professional only)

0400

Get DPMI Version

0500

Get Free Memory Information

0501

Allocate Memory Block

0502

Free Memory Block

0503

Resize Memory Block

0600

Lock Linear Region

0601

Unlock Linear Region

0604

Get Page Size (VM only)

0702

Mark Page as Demand Paging Candidate (DOS/4GW Professional only)

0703

Discard Page Contents (DOS/4GW Professional only)

0800

Physical Address Mapping

0801

Free Physical Address Mapping

0900

Get and Disable Virtual Interrupt State

0901

Get and Enable Virtual Interrupt State

0902

Get Virtual Interrupt State

0A00

Get Tenberry Software API Entry Point

0E00

Get Coprocessor Status

0E01

Set Coprocessor Emulation

DOS/4GW:  Addressing

3a.  Converting between pointers and linear addresses.

Because DOS/4GW uses a zero-based flat memory model, converting between pointers and linear addresses is trivial.  A pointer value is always relative to the current segment (the value in CS for a code pointer, or in DS or SS for a data pointer).  The segment bases for the default DS, SS, and CS are all zero.  Hence a near pointer is exactly the same thing as a linear address:  a null pointer points to linear address 0, and a pointer with value 0x10000 points to linear address 0x10000.

3b.  Converting between code and data pointers.

Because DS and CS have the same base address, they are natural aliases for each other.  To create a data alias for a code pointer, merely create a data pointer and set it equal to the code pointer.  It's not necessary for you to create your own alias descriptor.  Similarly, to create a code alias for a data pointer, merely create a code pointer and set it equal to the data pointer.

3c.  Converting between pointers and low memory addresses.

Linear addresses under 1 MB map directly to physical memory.  Hence the real-mode interrupt vector table is at address 0, the BIOS data segment is at address 0x400, the monochrome video memory is at address 0xB0000, and the color video memory is at address 0xB8000.  To read and write any of these, you can just use a pointer set to the proper address.  You don't need to create a far pointer, using some magic segment value.

3d.  Converting between linear and physical addresses.

Linear addresses at or above 1 MB do not map directly to physical memory, so you can not in general read or write extended memory directly, nor can you tell how a particular block of extended memory has been used.

DOS/4GW supports the DPMI call INT 31h/800h, which maps physical addresses to linear addresses.  In other words, if you have a peripheral device in your machine that has memory at a physical address of 256 MB, you can issue this call to create a linear address that points to that physical memory.  The linear address is the same thing as a near pointer to the memory and can be manipulated as such.

There is no way in a DPMI environment to determine the physical address corresponding to a given linear address.  This is part of the design of DPMI.  You must design your application accordingly.

3e.  Null pointer checking.

DOS/4GW will trap references to the first sixteen bytes of physical memory if you set the environment variable DOS4G=NULLP.   This is currently the only null-pointer check facility provided by DOS/4GW.

As of release 1.95, DOS/4GW traps both reads and writes.  Prior to this, it only trapped writes.

You may experience problems if you set DOS4G=NULLP and use some versions of the Open Watcom Debugger with a 1.95 or later extender.  These problems have been corrected in later versions of the Open Watcom Debugger.

DOS/4GW:  Interrupt and Exception Handling

4a.  Handling asynchronous interrupts.

Under DOS/4GW, there is a convenient way to handle asynchronous interrupts and an efficient way to handle them.

Because your CPU may be in either protected mode (when 32-bit code is executing) or real mode (a DOS or BIOS call) when a hardware interrupt comes in, you have to be prepared to handle interrupts in either mode.  Otherwise, you may miss interrupts.

You can handle both real-mode and protected-mode interrupts with a single handler, if 1) the interrupt is in the auto-passup range, 8 to 2Eh; and 2) you install a handler with INT 21h/25h or _dos_setvect(); 3) you do not install a handler for the same interrupt using any other mechanism.  DOS/4GW will route both protected-mode interrupts and real-mode interrupts to your protected-mode handler.  This is the convenient way.

The efficient way is to install separate real-mode and protected-mode handlers for your interrupt, so your CPU won't need to do unnecessary mode switches.  Writing a real-mode handler is tricky; all you can reasonably expect to do is save data in a buffer and IRET.  Your protected-mode code can periodically check the buffer and process any queued data.   (Remember, protected-mode code can access data and execute code in low memory, but real-mode code can't access data or execute code in extended memory.)

For performance, it doesn't matter how you install the real-mode handler, but we recommend the DPMI function INT 31h/201h for portability.

It does matter how you install the protected-mode handler.  You can't install it directly into the IDT, because a DPMI provider must distinguish between interrupts and exceptions and maintain separate handler chains.  Installing with INT 31h/205h is the recommended way to install your protected-mode handler for both performance and portability.

If you install a protected-mode handler with INT 21h/25h, both interrupts and exceptions will be funneled to your handler, to mimic DOS.  Since DPMI exception handlers and interrupt handlers are called with different stack frames, DOS/4GW executes a layer of code to cover these differences up; the same layer is used to support the DOS/4G API (not part of DOS/4GW).  This layer is the reason that hooking with INT 21h/25h is less efficient than hooking with INT 31h/205h.

4b.  Handling asynchronous interrupts in the second IRQ range.

Because the second IRQ range (normally INTs 70h-77h) is outside the DOS/4GW auto-passup range (8-2Eh, excluding 21h) you may not handle these interrupts with a single handler, as described above (the "convenient" method).  You must install separate real-mode and protected-mode handlers (the "efficient" method).

DOS/4G does allow you to specify additional passup interrupts, however.

4c.  Asynchronous interrupt handlers and DPMI.

The DPMI specification requires that all code and data referenced by a hardware interrupt handler MUST be locked at interrupt time.  A DPMI virtual memory manager can use the DOS file system to swap pages of memory to and from the disk; because DOS is not reentrant, a DPMI host is not required to be able to handle page faults during asynchronous interrupts.  Use INT 31h/600h (Lock Linear Region) to lock an address range in memory.

If you fail to lock all of your code and data, your program may run under DOS/4GW, but fail under the DOS/4GW Virtual Memory Manager or under another DPMI host such as Windows or OS/2.

You should also lock the code and data of a mouse callback function.

4d.  Open Watcom signal() function and Ctrl-Break.

In earlier versions of the Open Watcom C/C++ library, there was a bug that caused signal(SIGBREAK) not to work.  Calling signal(SIGBREAK) did not actually install an interrupt handler for Ctrl-Break (INT 1Bh), so Ctrl-Break would terminate the application rather than invoking the signal handler.

With these earlier versions of the library, you could work around this problem by hooking INT 1Bh directly.  With release 10.0, this problem has been fixed.

4e.  More tips on writing hardware interrupt handlers.

• It's more like handling interrupts in real mode than not.
  
  The same problems arise when writing hardware interrupt handlers for protected mode as arise for real mode.  We assume you know how to write real-mode handlers; if our suggestions don't seem clear, you might want to brush up on real-mode interrupt programming.
• Minimize the amount of time spent in your interrupt handlers.
  
  When your interrupt handlers are called, interrupts are disabled.  This means that no other system tasks can be performed until you enable interrupts (an STI instruction) or until your handler returns.  In general, it's a good idea to handle interrupts as quickly as possible.
• Minimize the amount of time spent in the DOS extender by installing separate real-mode and protected-mode handlers.
  
  If you use a passup interrupt handler, so that interrupts received in real mode are resignalled in protected mode by the extender, your application has to switch from real mode to protected mode to real mode once per interrupt.  Mode switching is a time-consuming process, and interrupts are disabled during a mode switch.  Therefore, if you're concerned about performance, you should install separate handlers for real-mode and protected-mode interrupts, eliminating the mode switch.
• If you can't just set a flag and return, enable interrupts (STI).
  
  Handlers that do more than just set a flag or store data in a buffer should re-enable interrupts as soon as it's safe to do so.  In other words, save your registers on the stack, establish your addressing conventions, switch stacks if you're going to - and then enable interrupts (STI), to give priority to other hardware interrupts.
• If you enable interrupts (STI), you should disable interrupts (CLI).
  
  Because some DPMI hosts virtualize the interrupt flag, if you do an STI in your handler, you should be sure to do a CLI before you return.  (CLI, then switch back to the original stack if you switched away, then restore registers, then IRET.) If you don't do this, the IRET will not necessarily restore the previous interrupt flag state, and your program may crash.  This is a difference from real-mode programming, and it tends to show up as a problem when you try running your program in a Windows or OS/2 DOS box for the first time (but not before).
• Add a reentrancy check.
  
  If your handler doesn't complete its work by the time the next interrupt is signalled, then interrupts can quickly nest to the point of overflowing the transfer stack.  This is a design flaw in your program, not in the DOS extender; a real-mode DOS program can have exactly the same behavior.  If you can conceive of a situation where your interrupt handler can be called again before the first instance returns, you need to code in a reentrancy check of some sort (before you switch stacks and enable interrupts (STI), obviously).
  
  Remember that interrupts can take different amounts of time to execute on different machines; the CPU manufacturer, CPU speed, speed of memory accesses, and CMOS settings (e.g.  "system BIOS shadowing") can all affect performance in subtle ways.  We recommend you program defensively and always check for unexpected reentry, to avoid transfer stack overflows.
• Switch to your own stack.
  
  Interrupt handlers are called on a stack that typically has only a small amount of stack available (512 bytes or less).   If you need to use more stack than this, you have to switch to your own stack on entry into the handler, and switch back before returning.
  
  If you want to use C run-time library functions, which are compiled for flat memory model (SS == DS, and the base of CS == the base of DS), you need to switch back to a stack in the flat data segment first.
  
  Note that switching stacks by itself won't prevent transfer stack overflows of the kind described above.

DOS/4GW:  Memory Management

5a.  Using the realloc() function.

In versions of Open Watcom C/C++ prior to 9.5b, there was a bug in the library implementation of realloc() under DOS/4GW and DOS/4GW Professional.  This bug was corrected by Open Watcom in the 9.5b release.

5b.  Using all of physical memory.

DOS/4GW Professional is currently limited to 64 MB of physical memory.  We do not expect to be able to fix this problem for at least six months.  If you need more than 64 MB of memory, you must use virtual memory.

DOS/4GW:  DOS, BIOS, and Mouse Services

6a.  Speeding up file I/O.

The best way to speed up DOS file I/O in DOS/4GW is to write large blocks (up to 65535 bytes, or the largest number that will fit in a 16-bit int) at a time from a buffer in low memory.  In this case, DOS/4GW has to copy the least amount of data and make the fewest number of DOS calls in order to process the I/O request.

Low memory is allocated through INT 31h/0100h, Allocate DOS Memory Block.  You can convert the real-mode segment address returned by INT 31h/0100h to a pointer (suitable for passing to setvbuf()) by shifting it left four bits.

6b.  Spawning.

It is possible to spawn one DOS/4GW application from another.  However, two copies of the DOS extender will be loaded into memory.  DOS/4G supports loading of multiple programs atop a single extender, as well as DLLs.

6c.  Mouse callbacks.

DOS/4GW Professional now supports the INT 31h interface for managing real-mode callbacks.  However, you don't need to bother with them for their single most important application:  mouse callback functions.  Just register your protected-mode mouse callback function as you would in real mode, by issuing INT 33h/0Ch with the event mask in CX and the function address in ES:EDX, and your function will work as expected.

Because a mouse callback function is called asynchronously, the same locking requirement exists for a mouse callback function as for a hardware interrupt handler.  See (4c) above.

6d.  VESA support.

While DOS/4GW automatically handles most INT 10h functions so that you can you can issue them from protected mode, it does not translate the INT 10h VESA extensions.  The workaround is to use INT 31h/300h (Simulate Real-Mode Interrupt).

DOS/4GW:  Virtual Memory

7a.  Testing for the presence of VMM.

INT 31h/400h returns a value (BX, bit 2) that tells if virtual memory is available.  Under a DPMI host such as Windows 3.1, this will be the host's virtual memory manager, not DOS/4GW's.

You can test for the presence of a DOS/4G-family DOS extender with INT 31h/0A00h, with a pointer to the null-terminated string "RATIONAL DOS/4G" in DS:ESI.  If the function returns with carry clear, a DOS/4G-family extender is running.

7b.  Reserving memory for a spawned application.

If you spawn one DOS/4GW application from another, you should set the DELETESWAP configuration option (i.e., SET DOS4GVM=deleteswap) so that the two applications don't try to use the same swap file.  You should also set the MAXMEM option low enough so that the parent application doesn't take all available physical memory; memory that's been reserved by the parent application is not available to the child application.

7c.  Instability under VMM.

A program that hooks hardware interrupts, and works fine without VMM but crashes sporadically with it, probably needs to lock the code and data for its hardware interrupt handlers down in memory.  DOS/4GW does not support page faults during hardware interrupts, because DOS services may not be available at that time.  See (4c) and (6c) above.

Memory can be locked down with INT 31h/600h (Lock Linear Region).

7d.  Running out of memory with a huge virtual address space.

Because DOS/4GW has to create page tables to describe your virtual address space, we recommend that you set your VIRTUALSIZE parameter just large enough to accommodate your program.  If you set your VIRTUALSIZE to 4 GB, the physical memory occupied by the page tables will be 4 MB, and that memory will not be available to DOS/4GW.

7e.  Reducing the size of the swap file.

DOS/4GW will normally create a swap file equal to your VIRTUALSIZE setting, for efficiency.  However, if you set the SWAPMIN parameter to a size (in KB), DOS/4GW will start with a swap file of that size, and will grow the swap file when it has to.  The SWAPINC value (default 64 KB) controls the incremental size by which the swap file will grow.

7f.  Deleting the swap file.

The DELETESWAP option has two effects:  telling DOS/4GW to delete the swap file when it exits, and causing DOS/4GW to provide a unique swap file name if an explicit SWAPNAME setting was not given.

DELETESWAP is required if one DOS/4GW application is to spawn another; see (7b) above.

7g.  Improving demand-load performance of large static arrays.

DOS/4GW demand-loading feature normally cuts the load time of a large program drastically.  However, if your program has large amounts of global, zero-initialized data (storage class BSS), the Open Watcom startup code will explicitly zero it (version 9.5a or earlier).  Because the zeroing operation touches every page of the data, the benefits of demand-loading are lost.

Demand loading can be made fast again by taking advantage of the fact that DOS/4GW automatically zeroes pages of BSS data as they are loaded.  You can make this change yourself by inserting a few lines into the startup routine, assembling it (MASM 6.0 will work), and listing the modified object module first when you link your program.

Here are the changes for \watcom\src\startup\386\cstart3r.asm (startup module from the C/C++ 9.5 compiler, library using register calling conventions).  You can modify the workaround easily for other Open Watcom compilers:

     
             ...                      ; cstart3r.asm, circa line 332
                                      ; end of _BSS segment (start of STACK)
             mov     ecx,offset DGROUP:_end
                                      ; start of _BSS segment
             mov     edi,offset DGROUP:_edata
     ;-------------------------------; RSI OPTIMIZATION
             mov     eax, edi         ; minimize _BSS initialization loop
             or      eax, 0FFFh       ; compute address of first page after
             inc     eax              ;   start of _BSS
             cmp     eax, ecx         ; if _BSS extends onto that page,
             jae     allzero          ;   then we can rely on the loader
             mov     ecx, eax         ;   zeroing the remaining pages
     allzero:                         ;
     ;-------------------------------; END RSI OPTIMIZATION
             sub     ecx,edi          ; calc # of bytes in _BSS segment
             mov     dl,cl            ; save bottom 2 bits of count in edx
             shr     ecx,2            ; calc # of dwords
             sub     eax,eax          ; zero the _BSS segment
             rep     stosd            ; ...
             mov     cl,dl            ; get bottom 2 bits of count
             and     cl,3             ; ...
             rep     stosb            ; ...
             ...

Note that the 9.5b and later versions of the Open Watcom C library already contain this enhancement.

7h.  How should I configure VM for best performance?

Here are some recommendations for setting up the DOS/4GW virtual memory manager.

VIRTUALSIZE

Set to no more than twice the total amount of memory (virtual and otherwise) your program requires.  If your program has 16 MB of code and data, set to 32 MB.  (There is only a small penalty for setting this value larger than you will need, but your program won't run if you set it too low.) See (7d) above.

MINMEM

Set to the minimum hardware requirement for running your application.  (If you require a 2 MB machine, set to 2048).

MAXMEM

Set to the maximum amount of memory you want your application to use.  If you don't spawn any other applications, set this large (e.g., 32000) to make sure you can use all available physical memory.  If you do spawn, see (7b) above.

SWAPMIN

Don't use this if you want the best possible VM performance.  The trade-off is that DOS/4GW will create a swap file as big as your VIRTUALSIZE.

SWAPINC

Don't use this if you want the best possible VM performance.

DELETESWAP

DOS/4GW's VM will start up slightly slower if it has to create the swap file afresh each time.  However, unless your swap file is very large, DELETESWAP is a reasonable choice; it may be required if you spawn another DOS/4GW program at the same time.  See (7b) above.

DOS/4GW:  Debugging

8a.  Attempting to debug a bound application.

You can't debug a bound application.  The 4GWBIND utility (included with DOS/4GW Professional) will allow you to take apart a bound application so that you can debug it:

     
     4GWBIND -U <boundapp.exe> <yourapp.exe>

8b.  Debugging with an old version of the Open Watcom debugger.

DOS/4GW supports versions 8.5 and up of the Open Watcom C, C++ and FORTRAN compilers.  However, in order to debug your unbound application with a Open Watcom debugger, you must have version 9.5a or later of the debugger.

If you have an older version of the debugger, we strongly recommend that you contact Open Watcom to upgrade your compiler and tools.  The only way to debug a DOS/4GW Professional application with an old version of the debugger is to rename 4GWPRO.EXE to DOS4GW.EXE and make sure that it's either in the current directory or the first DOS4GW.EXE on the DOS PATH.

Tenberry will not provide technical support for this configuration; it's up to you to keep track of which DOS extender is which.

8c.  Meaning of "unexpected interrupt" message/error 2001.

In version 1.95 of DOS/4GW, we revised the "unexpected interrupt" message to make it easier to understand.

For example, the message:

     
     Unexpected interrupt 0E (code 0) at 168:10421034

is now printed:

     
     error (2001): exception 0Eh (page fault) at 168:10421034

followed by a register dump, as before.

This message indicates that the processor detected some form of programming error and signaled an exception, which DOS/4GW trapped and reported.  Exceptions which can be trapped include:

     
     00h     divide by zero
     01h     debug exception OR null pointer used
     03h     breakpoint
     04h     overflow
     05h     bounds
     06h     invalid opcode
     07h     device not available
     08h     double fault
     09h     overrun
     0Ah     invalid TSS
     0Bh     segment not present
     0Ch     stack fault
     0Dh     general protection fault
     0Eh     page fault

When you receive this message, this is the recommended course of action:

1. Record all of the information from the register dump.
2. Determine the circumstances under which your program fails.
3. Consult your debugger manual, or an Intel 386, 486 or Pentium Programmer's Reference Manual, to determine the circumstances under which the processor will generate the reported exception.
4. Get the program to fail under your debugger, which should stop the program as soon as the exception occurs.
5. Determine from the exception context why the processor generated an exception in this particular instance.

8d.  Meaning of "transfer stack overflow" message/error 2002.

In version 1.95 of DOS/4GW, we added more information to the "transfer stack overflow" message.  The message (which is now followed by a register dump) is printed:

     
     error (2002): transfer stack overflow
     on interrupt <number> at <address>

This message means DOS/4GW detected an overflow on its interrupt handling stack.  It usually indicates either a recursive fault, or a hardware interrupt handler that can't keep up with the rate at which interrupts are occurring.  The best way to understand the problem is to use the VERBOSE option in DOS/4GW to dump the interrupt history on the transfer stack; see (8e) below.

8e.  Making the most of a DOS/4GW register dump.

If you can't understand your problem by running it under a debugger, the DOS/4GW register dump is your best debugging tool.  To maximize the information available for postmortem debugging, set the environment variable DOS4G to VERBOSE, then reproduce the crash and record the output.

Here's a typical register dump with VERBOSE turned on, with annotations.

  
  1 DOS/4GW error (2001): exception 0Eh (page fault)
                                                  at 170:0042C1B2
  2 TSF32: prev_tsf32 67D8
  3 SS       178 DS       178 ES        178 FS         0 GS        20
    EAX 1F000000 EBX        0 ECX   43201C EDX         E
    ESI        E EDI        0 EBP   431410 ESP   4313FC
    CS:IP  170:0042C1B2 ID 0E COD        0 FLG     10246
  4 CS=  170, USE32, page granular, limit FFFFFFFF, base        0, acc CF9B
    SS=  178, USE32, page granular, limit FFFFFFFF, base        0, acc CF93
    DS=  178, USE32, page granular, limit FFFFFFFF, base        0, acc CF93
    ES=  178, USE32, page granular, limit FFFFFFFF, base        0, acc CF93
    FS=    0, USE16, byte granular, limit        0, base       15, acc  0
    GS=   20, USE16, byte granular, limit     FFFF, base      6AA0, acc 93
  5 CR0: PG:1 ET:1 TS:0 EM:0 MP:0 PE:1   CR2: 1F000000 CR3: 9067
  6 Crash address (unrelocated) = 1:000001B2
  7 Opcode stream: 8A 18 31 D2 88 DA EB 0E 50 68 39 00 43 00 E8 1D
    Stack:
  8 0178:004313FC 000E 0000 0000 0000 C2D5 0042 C057 0042 0170 0000 0000 0000
    0178:00431414 0450 0043 0452 0043 0000 0000 1430 0043 CBEF 0042 011C 0000
    0178:0043142C C568 0042 0000 0000 0000 0000 0000 0000 F248 0042 F5F8 0042
    0178:00431444 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000
    0178:0043145C 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000
    0178:00431474 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000
  9 Last 4 ints: 21 @ 170:42CF48/21 @ 170:42CF48/21 @ 170:42CF48/E @ 170:42C1B2/

1. The error message includes a synopsis of the problem.  In this case, the processor signaled a page fault exception while executing at address 170:0042C1B2.
2. The prev_tsf32 field is not usually of interest.
3. These are the register values at the time of the exception.  The interrupt number and error code (pushed on the stack by the processor for certain exceptions) are also printed.
4. The descriptors referenced by each segment register are described for your convenience.  USE32 segments in general belong to your program; USE16 segments generally belong to the DOS extender.  Here, CS points to your program's code segment, and SS, DS, and ES point to your data segment.  FS is NULL and GS points to a DOS extender segment.
5. The control register information is not of any general interest, except on a page fault, when CR2 contains the address value that caused the fault.  Since EAX in this case contains the same value, an attempt to dereference EAX could have caused this particular fault.
6. If the crash address (unrelocated) appears, it tells you where the crash occurred relative to your program's link map.   You can therefore tell where a crash occurred even if you can't reproduce the crash in a debugger.
7. The opcode stream, if it appears, shows the next 16 bytes from the code segment at the point of the exception.  If you disassemble these instructions, you can tell what instructions caused the crash, even without using a debugger.  In this case, 8A 18 is the instruction mov bl,[eax].
8. 72 words from the top of the stack, at the point of the exception, may be listed next.  You may be able to recognize function calls or data from your program on the stack.
9. The four interrupts least to most recently handled by DOS/4GW in protected mode are listed next.  In this example, the last interrupt issued before the page fault occurred was an INT 21h (DOS call) at address 170:42CF48.  Sometimes, this information provides helpful context.

Here's an abridged register dump from a stack overflow.

  
    DOS/4GW error (2002): transfer stack overflow
                                     on interrupt 70h at 170:0042C002
    TSF32: prev_tsf32 48C8
    SS        C8 DS       170 ES         28 FS         0 GS         20
    EAX AAAAAAAA EBX BBBBBBBB ECX CCCCCCCC EDX DDDDDDDD
    ESI 51515151 EDI D1D1D1D1 EBP B1B1B1B1 ESP     4884
  1 CS:IP  170:0042C002 ID 70 COD        0 FLG         2
    ...
  2 Previous TSF:
    TSF32: prev_tsf32 498C
    SS        C8 DS       170 ES         28 FS         0 GS         20
    EAX AAAAAAAA EBX BBBBBBBB ECX CCCCCCCC EDX DDDDDDDD
    ESI 51515151 EDI D1D1D1D1 EBP B1B1B1B1 ESP     4960
  3 CS:IP  170:0042C002 ID 70 COD        0 FLG         2
    ...
    Previous TSF:
    TSF32: prev_tsf32 67E4
    SS       178 DS       170 ES         28 FS         0 GS         20
    EAX AAAAAAAA EBX BBBBBBBB ECX CCCCCCCC EDX DDDDDDDD
    ESI 51515151 EDI D1D1D1D1 EBP B1B1B1B1 ESP   42FFE0
  4 CS:IP  170:0042C039 ID 70 COD        0 FLG       202
  5 Opcode stream: CF 66 B8 62 25 66 8C CB 66 8E DB BA 00 C0 42 00
    Last 4 ints: 70 @ 170:42C002/70 @ 170:42C002/70 @ 170:42C002/70 @ 170:42C002/

1. We overflowed the transfer stack while trying to process an interrupt 70h at 170:0042C002.
2. The entire interrupt history from the transfer stack is printed next.  The prev_tsf32 numbers increase as we progress from most recent to least recent interrupt.  All of these interrupts are still pending, which is why we ran out of stack space.
3. Before we overflowed the stack, we got the same interrupt at the same address.  For a recursive interrupt situation, this is typical.
4. The oldest frame on the transfer stack shows the recursion was touched off at a slightly different address.  Looking at this address may help you understand the recursion.
5. The opcode stream and last four interrupt information comes from the newest transfer stack frame, not the oldest.

DOS/4GW:  Compatibility

9a.  Running DOS/4GW applications from inside Lotus 1-2-3.

In order to run DOS/4GW applications while "shelled out" from Lotus 1-2-3, you must use the PRIVATXM program included with your Open Watcom compiler.  Otherwise, 1-2-3 will take all of the memory on your machine and prevent DOS/4GW from using it.

Before starting 1-2-3, you must set the DOS16M environment variable to limit Lotus' memory use (see your Open Watcom manual).  After shelling out, you must run PRIVATXM, then clear the DOS16M environment variable before running your application.

9b.  EMM386.EXE provided with DOS 6.0.

We know of at least three serious bugs in the EMM386.EXE distributed with MS-DOS 6.0, one involving mis-counting the amount of available memory, one involving mapping too little of the High Memory Area (HMA) into its page tables, and one involving allocation of EMS memory.  Version 1.95 of DOS/4GW contains workarounds for some of these problems.

If you are having problems with DOS/4GW and you are using an EMM386.EXE dated 3-10-93 at 6:00:00, or later, you may wish to try the following workarounds, in sequence, until the problem goes away.

• Configure EMM386 with both the NOEMS and NOVCPI options.
• Convert the DEVICEHIGH statements in your CONFIG.SYS to DEVICE statements, and remove the LH (Load High) commands from your AUTOEXEC.BAT.
• Run in a Windows DOS box.
• Replace EMM386 with another memory manager, such as QEMM-386, 386Max, or an older version of EMM386.
• Run with HIMEM.SYS alone.

You may also wish to contact Microsoft Corporation to inquire about the availability of a fix.

9c.  Spawning under OS/2 2.1.

We know of a bug in OS/2 2.1 that prevents one DOS/4GW application from spawning another over and over again.  The actual number of repeated spawns that are possible under OS/2 varies from machine to machine, but is generally about 30.

This bug also affects programs running under other DOS extenders, and we have not yet found a workaround, other than linking your two programs together as a single program.

9d.  "DPMI host error:  cannot lock stack".

This error message almost always indicates insufficient memory, rather than a real incompatibility.  If you see it under an OS/2 DOS box, you probably need to edit your DOS Session settings and make DPMI_MEMORY_LIMIT larger.

9e.  Bug in Novell TCPIP driver.

Some versions of a program from Novell called TCPIP.EXE, a real-mode program, will cause the high words of EAX and EDX to be altered during a hardware interrupt.  This bug breaks protected-mode software (and other real-mode software that uses the 80386 registers).  Novell has released a newer version of TCPIP that fixes the problem; contact Novell to obtain the fix.

9f.  Bugs in Windows NT.

The initial release of Windows NT includes a DPMI host, DOSX.EXE, with several serious bugs, some of which apparently cannot be worked around.  We cannot warranty operation of DOS/4GW under Windows NT at this time, but we are continuing to exercise our best efforts to work around these problems.

You may wish to contact Microsoft Corporation to inquire about the availability of a new version of DOSX.EXE.

16-bit Windows:  Creating 16-bit Windows 3.x Applications

16-bit Windows:  The Sample GUI Application

16-bit Windows:  Building and Running the GUI Application

16-bit Windows:  Debugging the GUI Application

16-bit Windows:  Porting Non-GUI Applications to 16-bit Windows 3.x

16-bit Windows:  Console Device in a Windowed Environment

16-bit Windows:  The Sample Non-GUI Application

16-bit Windows:  Building and Running the Non-GUI Application

16-bit Windows:  Debugging the Non-GUI Application

16-bit Windows:  Default Windowing Library Functions

dwfDeleteOnClose

     
     integer function dwfDeleteOnClose( unit )
     integer unit

This function tells the console window that it should close itself when the file is closed.  You must pass to it the unit number associated with the opened console.

dwfSetAboutDlg

     
     integer function dwfSetAboutDlg( title, text )
     character*(*) title
     character*(*) text

This function sets the about dialog box of the default windowing system.  The "title" points to the string that will replace the current title.  If title is CHAR(0) then the title will not be replaced.  The "text" points to a string which will be placed in the about box.  To get multiple lines, embed a new line after each logical line in the string.  If "text" is CHAR(0), then the current text in the about box will not be replaced.

dwfSetAppTitle

     
     integer function dwfSetAppTitle( title )
     character*(*) title

This function sets the main window's title.

dwfSetConTitle

     
     integer function dwfSetConTitle( unit, title )
     integer unit
     character*(*) title

This function sets the console window's title which corresponds to the unit number passed to it.

dwfShutDown

     
     integer function dwfShutDown()

This function shuts down the default windowing I/O system.  The application will continue to execute but no windows will be available for output.

dwfYield

     
     integer function dwfYield()

This function yields control back to the operating system, thereby giving other processes a chance to run.

32-bit Windows:  Creating 32-bit Windows 3.x Applications

32-bit Windows:  The Sample GUI Application

32-bit Windows:  Building and Running the GUI Application

1. WBIND copies WIN386.EXT into the current directory.
2. WBIND.EXE optionally runs the resource compiler on the 32-bit Windows supervisor so that the 32-bit executable can have access to the applications resources.
3. WBIND.EXE concatenates WIN386.EXT and the ".rex" file, and creates a ".exe" file with the same name as the ".rex" file.

WBIND

is the name of the Open Watcom Bind utility.

file_spec

is the name of the 32-bit Windows EXE to bind.

-d

requests that a 32-bit DLL be built.

-n

indicates that the resource compiler is NOT to be invoked.

-q

requests that WBIND run in quiet mode (no informational messages are displayed).

-s supervisor

specifies the path and name of the Windows supervisor to be bound with the application.  If not specified, a search of the paths listed in the PATH environment variable is performed.  If this search is not successful and the WATCOM environment variable is defined, the %WATCOM%\BINW directory is searched.

-R rc_options

all options after -R are passed to the resource compiler.

32-bit Windows:  Debugging the GUI Application

32-bit Windows:  Porting Non-GUI Applications to 32-bit Windows 3.x

32-bit Windows:  Console Device in a Windowed Environment

32-bit Windows:  The Sample Non-GUI Application

32-bit Windows:  Building and Running the Non-GUI Application

1. WBIND copies WIN386.EXT into the current directory.
2. WBIND.EXE optionally runs the resource compiler on the 32-bit Windows supervisor so that the 32-bit executable can have access to the applications resources.
3. WBIND.EXE concatenates WIN386.EXT and the ".rex" file, and creates a ".exe" file with the same name as the ".rex" file.

WBIND

is the name of the Open Watcom Bind utility.

file_spec

is the name of the 32-bit Windows EXE to bind.

-d

requests that a 32-bit DLL be built.

-n

indicates that the resource compiler is NOT to be invoked.

-q

requests that WBIND run in quiet mode (no informational messages are displayed).

-s supervisor

specifies the path and name of the Windows supervisor to be bound with the application.  If not specified, a search of the paths listed in the PATH environment variable is performed.  If this search is not successful and the WATCOM environment variable is defined, the %WATCOM%\BINW directory is searched.

-R rc_options

all options after -R are passed to the resource compiler.

32-bit Windows:  Debugging the Non-GUI Application

32-bit Windows:  Default Windowing Library Functions

dwfDeleteOnClose

     
     integer function dwfDeleteOnClose( unit )
     integer unit

This function tells the console window that it should close itself when the file is closed.  You must pass to it the unit number associated with the opened console.

dwfSetAboutDlg

     
     integer function dwfSetAboutDlg( title, text )
     character*(*) title
     character*(*) text

This function sets the about dialog box of the default windowing system.  The "title" points to the string that will replace the current title.  If title is CHAR(0) then the title will not be replaced.  The "text" points to a string which will be placed in the about box.  To get multiple lines, embed a new line after each logical line in the string.  If "text" is CHAR(0), then the current text in the about box will not be replaced.

dwfSetAppTitle

     
     integer function dwfSetAppTitle( title )
     character*(*) title

This function sets the main window's title.

dwfSetConTitle

     
     integer function dwfSetConTitle( unit, title )
     integer unit
     character*(*) title

This function sets the console window's title which corresponds to the unit number passed to it.

dwfShutDown

     
     integer function dwfShutDown()

This function shuts down the default windowing I/O system.  The application will continue to execute but no windows will be available for output.

dwfYield

     
     integer function dwfYield()

This function yields control back to the operating system, thereby giving other processes a chance to run.

Windows:  The Open Watcom 32-bit Windows 3.x Extender

Windows:  Pointers

Windows:  Implementation Overview

Windows:  System Structure

Windows:  System Overview

• WIN386.EXT is the key component of a 32-bit Windows application.  It is a 16-bit Windows application which contains:
  • All application resources.
  • A 16-bit local heap.
  • A 16-bit stack.
• W386DLL.EXT is similar to WIN386.EXT, only it provides a DLL interface.
  
  WIN386.EXT is bound to your 32-bit application to create a 32-bit application that will run under Windows 3.x.  WIN386.EXT provides the following functionality:
  • supervisor to bring the 32-bit application into memory and start it running.
  • "glue" functions to connect to Windows for both API and DOS functionality.  This interface is designed to transparently set up the calling functions' pointers and parameters to their 16-bit counterparts.
  • "glue-back" functions to allow Windows to call back 32-bit routines.
  • special code to allow debugging of 32-bit applications.
• A number of files with file extension .fi are located in the \WATCOM\SRC\FORTRAN\WIN directory.  The file WINAPI.FI describes the calling convention of each Windows API function.  Other files define Windows constants and data structures.
• WIN386.LIB contains all the necessary library functions to connect to the 32-bit supervisor WIN386.EXT.   All Windows API calls and Open Watcom FORTRAN 77 library DOS calls are found here.
• The standard FORTRAN 77 and C library functions, specially modified to run in the 32-bit environment, are located in the \WATCOM\LIB386\WIN directory.
• WBIND.EXE merges your 32-bit executable and the appropriate Supervisor into a single executable.

Windows:  Steps to Obtaining a 32-bit Application

1. If you are starting with a 16-bit Windows application, you must adapt your source code to the 32-bit environment.
2. You must compile the application using a 32-bit compiler.
3. You must link the application with the 32-bit libraries.
4. You must bind the 32-bit application with the 32-bit supervisor.
5. You can then run and/or debug the application.

Windows:  Windows 3.x 32-bit Programming Overview

• WINAPI.FI and WINDOWS.FI
• Environment Notes
• Floating-point Emulation
• Multiple Instances
• Pointer Handling
• When To Convert Incoming Pointers
• When To Convert Outgoing Pointers
• SendMessage and SendDlgItemMessage
• GlobalAlloc and LocalAlloc
• Callback Function Pointers
• Window Sub-classing
• Calling 16-bit DLLs
• _16 Functions

Windows:  WINAPI.FI

Windows:  Environment Notes

• The 32-bit Windows Supervisor uses the first 256 bytes of the 32-bit application's stack to save state information.  If this is corrupted, your application will abnormally terminate.
• The 32-bit Windows Supervisor provides resources for up to 512 callback routines.  Note that this restriction is only on the maximum number of active callbacks.

Windows:  Floating-point Emulation

Windows:  Multiple Instances

Windows:  Pointer Handling

Windows:  When To Convert Incoming Pointers

• LocalLock
• GlobalLock
• the lParam in a window callback routine (if it is a pointer)

Windows:  When To Convert Outgoing Pointers

Windows:  SendMessage and SendDlgItemMessage

• combo boxes (CB_ messages)
• edit controls (EM_ messages)
• list boxes (LB_ messages)
• certain windows messages (WM_ messages);

• CB_ADDSTRING, CB_FINDSTRING, CB_FINDSTRINGEXACT, CB_INSERTSTRING will not need a conversion if the combo box was created as owner-draw style without CBS_HASSTRINGS style.
• LB_ADDSTRING, LB_FINDSTRING, LB_FINDSTRINGEXACT, LB_INSERTSTRING will not need a conversion if the list box was created as owner-draw style without LBS_HASSTRINGS style.

Windows:  GlobalAlloc and LocalAlloc

Windows:  Callback Function Pointers

• ChooseColor
• ChooseFont
• CreateDialog
• CreateDialogIndirect
• CreateDialogIndirectParam
• CreateDialogParam
• DialogBox
• DialogBoxIndirect
• DialogBoxIndirectParam
• DialogBoxParam
• EnumChildWindows
• EnumFonts
• EnumMetaFile
• EnumObjects
• EnumProps
• EnumTaskWindows
• EnumWindows
• Escape (SETABORTPROC option)
• FindText
• GetOpenFileName
• GetSaveFileName
• GlobalNotify
• GrayString
• LineDDA
• PrintDlg
• RegisterClass
• ReplaceText
• SetClassLong (GCL_WNDPROC option)
• SetResourceHandler
• SetTimer
• SetWindowLong (GWL_WNDPROC option)
• SetWindowsHook

• FreeProcInstance
• MakeProcInstance
• UnhookWindowsHook

1. The call to MakeProcInstance and FreeProcInstance for the callback function occurs in a module with NOAUTOPROCS defined.
2. No Windows API functions (listed above) are used in the module with NOAUTOPROCS defined.  If they are, you must code the general case to use them.

Windows:  Window Sub-classing

Windows:  Calling 16-bit DLLs

Character

Parameter Type

c

call a 'cdecl' function as opposed to a 'pascal' function (if specified, it must be listed first)

b

unsigned BYTE

w

16-bit WORD

d

32-bit DWORD

f

double precision floating-point

p

32-bit flat pointer (converted to 16:16 far pointer)

Windows:  _16 Functions

Windows:  Windows 32-Bit Dynamic Link Libraries

Windows:  A Sample 32-bit DLL

Windows:  Calling Functions in a 32-bit DLL from a 16-bit Application

Windows:  Calling Functions in a 32-bit DLL from a 32-bit Application

Windows:  A Sample 32-bit DLL Using a Structure

Windows:  Creating and Debugging Dynamic Link Libraries

WINDLLV.FOR

is the source code for a simple 32-bit DLL containing two library routines that use integer arguments to pass information.

GEN16V.FOR

is the source code for a generic 16-bit Windows application that calls functions in the "WINDLLV" 32-bit Windows DLL.

GEN32V.FOR

is the source code for a generic 32-bit Windows application that calls functions in the "WINDLLV" 32-bit Windows DLL.

WINDLL.FOR

is the source code for a simple 32-bit DLL containing two library routines that use structures to pass information.

GEN16.FOR

is the source code for a generic 16-bit Windows application that calls functions in the "WINDLL" 32-bit Windows DLL.

GEN32.FOR

is the source code for a generic 32-bit Windows application that calls functions in the "WINDLL" 32-bit Windows DLL.

MAKEFILE

is a makefile for compiling and linking the programs described above.

Windows:  Building the Applications

Windows:  Installing the Examples under Windows

1. Select the "New..." entry from the "File" menu of the Microsoft Windows Program Manager.
2. Select "Program Item" from the "New Program Object" window and press the "OK" button.
3. Enter "16-bit DLL Test" as a description for the GEN16V program.  Enter the full path to the GEN16V program as a command line.
   
   Example:
   
        Description:    16-bit DLL Test
        Command Line:   c:\work\dll\gen16v.exe
4. Enter "32-bit DLL Test" as a description for the GEN32V program.  Enter the full path to the GEN32V program as a command line.
   
   Example:
   
        Description:    32-bit DLL Test
        Command Line:   c:\work\dll\gen32v.exe

Windows:  Running the Examples

Windows:  Debugging a 32-bit DLL