_xvheaplock()
 Lock an allocated block of segment heap memory
------------------------------------------------------------------------------
 C Prototype

     #include "vm.api"
     FARP _xvheaplock(
                       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

     _xvheaplock() returns a far pointer to the allocated memory block, or a
     NULL pointer, if either argument is invalid.

 Description

     _xvheaplock() locks the entire segment heap, guaranteeing that the
     allocated memory block is located in conventional memory and will not be
     moved or swapped out by the VMM system.  The pointer returned is valid
     until all blocks of memory within the segment are unlocked using
     _xvheapunlock().

     Warning!  Do not leave a memory block locked unnecessarily.  Because
     all locked segments reside in conventional memory, the more of them you
     lock, the greater the chance of exhausting conventional memory.
     Therefore, always unlock a memory block with _xvheapunlock() when you
     are not actively accessing it.  Typically, this will mean locking and
     unlocking the same memory block several times within one function call.

     You must eventually unlock memory blocks locked by _xvheaplock() using
     _xvheapunlock().

 Notes

     .  Error conditions:  If there is not enough VM swap space available
        for the segment to be loaded into conventional memory, the system
        raises an internal error and halts.

 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.