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