_xvheapdestroy()
 Free the segment allocated for a segment heap
------------------------------------------------------------------------------
 C Prototype

     #include "vm.api"
     void _xvheapdestroy(
                          HANDLE hSegment
                        )

 Arguments

     hSegment is the VM segment handle returned by _xvheapnew().

 Returns

     _xvheapdestroy() has no return value.

 Description

     _xvheapdestroy() frees a VM segment previously allocated as a segment
     heap with _xvheapnew() and invalidates the handle of that segment.

     Warning!  _xvheapdestroy() frees the entire segment heap.  Before
     using this function, you must use_xvheapfree() to free all memory blocks
     allocated within the segment heap.

 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.