_xvheapunlock()
 Unlock an allocated block of segment heap memory
------------------------------------------------------------------------------
 C Prototype

     #include "vm.api"
     void _xvheapunlock(
                         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

     _xvheapunlock() has no return value.

 Description

     _xvheapunlock() unlocks a block of allocated memory previously locked by
     _xvheaplock(), and invalidates any pointers to it.

     Note:  _xvheaplock() locks the entire segment heap so that it cannot
     be moved or swapped out until all blocks of memory within it are
     unlocked with _xvheapunlock().

     Warning!  After you unlock a memory block, you should not attempt to
     access it with the far pointer returned by _xvheaplock() since there is
     no guarantee that the memory block resides in the segment at that
     physical memory address.  If you need further access to the memory
     block, lock it again and use the new pointer returned by _xvheaplock().

 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.