Microsoft KB Archive/66475

INF: Using GlobalDosAlloc and GlobalDosFree ID Number: Q66475

3.00 WINDOWS

Summary:

The prototypes for the Windows API functions GlobalDosAlloc and GlobalDosFree are missing in WINDOWS.H. To use these functions, declare them as follows:

DWORD FAR PASCAL GlobalDosAlloc (DWORD dwSize); WORD FAR PASCAL GlobalDosFree (WORD wSelector);

GlobalDosFree frees a block of memory allocated with the GlobalDosAlloc function. The return value identifies the outcome of the function. If GlobalDosFree returns NULL, the function is successful. Otherwise, the return value is equal to wSelector. If GlobalDosAlloc is successful, the return value contains a paragraph- segment value in its high-order word and a selector in its low-order word. If GlobalDosAlloc fails, it returns NULL. The wSelector parameter to GlobalDosFree is the selector portion (low word) of the return value from a successful call to GlobalDosAlloc.

Note that, in enhanced mode Windows, memory allocated by GlobalDosAlloc is visible only in the Windows virtual machine. This memory cannot be used to communicate asynchronously (based on hardware interrupts, for example) with terminate-and-stay-resident (TSR) programs. For an example of a Windows application that communicates asynchronously with a TSR program, search this knowledge base on the words: TDOSMEM or GDOSMEM.

More Information:

The following code fragment demonstrates how to use these functions:

DWORD dwMyLowMemory; WORD wMySegment; WORD wMySelector; LPSTR lpProtModePtr; DWORD lpRealModePtr;. ..

if ((dwMyLowMemory = GlobalDosAlloc(dwSize)) == NULL) return FALSE; /* Error: unable to allocate memory */

/  GlobalDosAlloc allocates global memory that can be accessed by * real-mode applications. The memory is guaranteed to exist in the * first megabyte of linear address space.   GlobalDosAlloc returns a DWORD in which the high-order word is a * paragraph segment and the low-order word is a selector. */

wMySegment = HIWORD(dwMyLowMemory); wMySelector = LOWORD(dwMyLowMemory);

lpProtModePtr = (LPSTR)MAKELONG(0, wMySelector); // protect mode pointer

lpRealModePtr = (DWORD)MAKELONG(0, wMySegment); // real mode pointer. ..

if ((wMySelector = GlobalDosFree(wMySelector)) != NULL) return FALSE; /* Error: unable to free memory */

If GlobalDosAlloc is successful, the memory object will reside in memory below 1 MB. The value in wMySegment will be aligned on a paragraph boundary, and therefore the offset will always be zero.

This example is valid in all Windows modes. GlobalDosAlloc will return segment values in both words if Windows is running in real mode. If Windows cannot allocate a block of memory of the requested size, the return value is NULL.

Note: An application should not use these functions unless it is absolutely necessary. The memory pool from which objects are allocated is a scarce system resource. For more information, please refer to pages 4-236 and 4-237 in version 3.0 of the “Microsoft Windows Software Development Kit Reference Volume 1.”

Additional reference words: 3.0