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

 _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 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.