_xvheapalloc()
 Allocate a memory block from a segment heap
------------------------------------------------------------------------------
 C Prototype

     #include "vm.api"
     USHORT _xvheapalloc(
                          HANDLE hSegment,
                          USHORT uiSize
                        )

 Arguments

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

     uiSize is the number of bytes to allocate from the segment heap.

 Returns

     If successful, _xvheapalloc() returns the offset of the allocated memory
     block; otherwise, it returns zero.

 Description

     _xvheapalloc() allocates a memory block from within a segment heap.  If
     you request a size larger than the largest contiguous memory block
     within the segment heap (or larger than the segment heap itself), the
     function returns zero.

     If the memory is successfully allocated, _xvheapalloc() returns an
     offset into the segment heap.  You can use this offset, with the VM
     segment handle returned by _xvheapnew(), in all subsequent operations
     involving the allocated block.

     Note:  To use the allocated memory block, your function must obtain
     a far pointer to physical memory by locking the allocated memory with
     _xvheaplock().

     Warning!  You must eventually use _xvheapfree() to free memory
     blocks allocated by _xvheapalloc().

 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.