_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 the
        CA-Clipper 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 is 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.