Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_WINHEAP
 
HHEAP WinCreateHeap(selHeapBase, cbHeap, cbGrow, cbMinDed, cbMaxDed,
    fsOptions)
USHORT selHeapBase;    /* selector of the heap                   */
USHORT cbHeap;         /* initial heap size                      */
USHORT cbGrow;         /* number of bytes heap must grow         */
USHORT cbMinDed;       /* minimum number of dedicated free lists */
USHORT cbMaxDed;       /* maximum number of dedicated free lists */
USHORT fsOptions;      /* heap options                           */
 
The WinCreateHeap function creates a heap that can be used for memory
management.
 
Parameter    Description
────────────────────────────────────────────────────────────────────────────
 
selHeapBase  Specifies the selector of the segment that will contain the
             local heap.
 
cbHeap       Specifies the initial heap size (in bytes).
 
cbGrow       Specifies the minimum number of bytes by which the heap must be
             increased if it is too small to satisfy a memory allocation
             request (see the WinAllocMem and WinReallocMem functions). If
             this parameter is zero, the default value of 512 bytes is
             used.
 
cbMinDed     Specifies the minimum number of dedicated free lists.
 
cbMaxDed     Specifies the maximum number of dedicated free lists.
 
fsOptions    Specifies the optional characteristics for the heap. It may be
             one or more of the following values:
 
             Value         Meaning
             ───────────────────────────────────────────────────────────────
             HM_MOVEABLE   Specifies that the created heap supports movable
                           objects. WinAllocMem then reserves an additional
                           two words at the beginning of each allocated
                           object.
 
             HM_VALIDSIZE  Specifies that the heap manager should check the
                           size arguments to WinReallocMem and WinFreeMem
                           function calls against the two additional words
                           stored at the beginning of each allocated object.
                           This option is only valid if HM_MOVEABLE is also
                           specified.
 
Return Value
 
The return value is a handle to the heap, or zero if an error occurred.
 
Comments
 
There are three types of segments that can contain a heap:
 
♦  Automatic data segment of an application
 
♦  Automatic data segment of a dynamic-link package
 
♦  Segment allocated by the DosAllocSeg function (public or shared)
 
To accommodate these various targets for heaps, all four possible
combinations of the parameters are used to discriminate between the various
options.
 
These combinations are shown in the following list:
 
selHeapBase    cbHeap     Meaning
────────────────────────────────────────────────────────────────────────────
Zero           Zero       Caller is an application that places the heap at
                          the end of its automatic data segment. The size of
                          the heap was specified with the HEAPSIZE keyword
                          in the application's .def file to the linker. This
                          function extracts the heap-size parameter from the
                          local information segment and uses that many bytes
                          at the end of the caller's automatic data segment.
                          No reallocation of the data segment occurs, as the
                          loader already reserved space at the end of the
                          data segment, after the static data was loaded
                          from the .exe file.
 
Selector       Nonzero    Caller is a dynamic-link package that places a
                          heap at the end of its automatic data segment. The
                          cbHeap parameter must be less than or equal to the
                          HEAPSIZE value from the .def file that was passed
                          to the dynamic-link package's initialization entry
                          point in the cx register. Otherwise, this function
                          may produce incorrect results.
 
Selector       Zero       Caller is either an application or a dynamic-link
                          package that has explicitly allocated a segment
                          using the DosAllocSeg function and places a heap
                          in that segment. The heap is placed at the
                          beginning of the segment and the size of the
                          segment (determined by using DosSizeSeg) is the
                          size of the heap.
 
Zero           Nonzero    Caller is either an application or a dynamic-link
                          package that places a heap of a specific size in a
                          separate segment but does not call DosAllocSeg.
                          For information about accessing the segment
                          implicitly allocated by WinCreateHeap when called
                          with this combination of parameters, see the
                          WinLockHeap function.
 
See Also
 
DosAllocSeg, DosSizeSeg, WinAllocMem, WinDestroyHeap, WinFreeMem,
WinLockHeap, WinReallocMem
 
                                      ♦