_xvheapfree()
 Free an allocated block of segment heap memory
------------------------------------------------------------------------------
 C Prototype

     #include "vm.api"
     void _xvheapfree(
                       HANDLE hSegment,
                       USHORT uiOffset
                     )

 Arguments

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

     uiOffset is the offset of the allocated memory block returned by
     _xvheapalloc().

 Returns

     _xvheapfree() has no return value.

 Description

     _xvheapfree() frees a memory block previously allocated in a segment
     heap by _xvheapalloc() and then invalidates the offset for that memory
     block.

     Note:  _xvheapfree() only frees blocks of memory allocated within
     the segment heap.  After all allocated blocks of memory within the
     segment heap have been freed, use _xvheapdestroy() to free the entire
     segment heap.

     Warning!  Do not use _xvheapfree() to free a locked memory block.
     Unlock the memory block first using _xvheapunlock().

 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.