Click above to get retro games delivered to your door ever month!

 _xvheapnew()
 Allocate a VM segment for use as a segment heap
------------------------------------------------------------------------------
 C Prototype

     #include "vm.api"
     HANDLE _xvheapnew(
                        USHORT uiSize
                      )

 Arguments

     uiSize is the size of the VM segment to allocate as a segment heap.

 Returns

     If successful, _xvheapnew() returns a 16-bit segment handle; otherwise,
     it returns zero.

 Description

     _xvheapnew() allocates a VM segment for use as a segment heap.

     Warning!  You must eventually free a segment allocated by
     _xvheapnew() with _xvheapdestroy().

 Notes

     .  Actual heap size: In CA-Clipper, there are two bytes of overhead
        for every memory block allocated within the segment heap.  Therefore,
        you cannot use a segment heap to hold a string that approaches
        CA-Clipper's maximum string length (65,519 bytes).  In such cases,
        you should dedicate an entire VM segment to the string.

     .  Efficiency: The VMM system is most efficient when managing a small
        number of relatively large segments.  The segment heap functions
        allow a single segment to be treated as a C-style heap (using
        _xvheapalloc() and _xvheapfree()), making it possible to store
        multiple data items in one segment.  This can greatly increase the
        overall efficiency of the VMM system.

 Examples

     .  This example creates a segment heap with _xvheapnew() and
        allocates a memory block in the segment heap.  The block is then
        locked and the string copied into it.  Later, the memory block is
        unlocked, the memory freed, and the heap destroyed:

        // CA-Clipper include files
        #include "extend.api"
        #include "vm.api"

        // Microsoft C include files
        #include "string.h"

        // Prototype
        Boolean VMHeapExample(char * spSrc);

        #define HEAP_SIZE   4096

        Boolean VMHeapExample(char * spSrc)
        {
           HANDLE hSegment;
           unsigned uiStringOffset;
           unsigned uiBufflen;
           char * spString;
           Boolean bResult = FALSE;

           if (hSegment = _xvheapnew(HEAP_SIZE))
              {
              uiBufflen = strlen(spSrc) + 1;
              uiStringOffset = _xvheapalloc(hSegment, uiBufflen);
              if (uiStringOffset)
                 {
                 spString = _xvheaplock(hSegment, uiStringOffset);
                 if (spString != NULL)
                    {
                    strcpy(spString, spSrc);

                    .
                    . <statements>
                    .

                    bResult = TRUE;

                    _xvheapunlock(hSegment, uiStringOffset);
                    }
                 _xvheapfree(hSegment, uiStringOffset);
                 }
              _xvheapdestroy(hSegment);
              }

           return (bResult);
        }

 Files:  Library is CLIPPER.LIB, header file is Vm.api.