_xvunlock()
 Unlock a VM segment
------------------------------------------------------------------------------
 C Prototype

     #include "vm.api"
     void _xvunlock(
                     HANDLE hSegment
                   )

 Arguments

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

 Returns

     _xvunlock() has no return value.

 Description

     _xvunlock() unlocks a VM segment locked by _xvlock() and invalidates any
     pointers to the segment.  Unlocking the segment allows the VMM system to
     move or swap the segment if needed.

     Note:  If the segment's lock count (_xvlockcount()) is greater than
     one, the lock count is decremented but the segment remains locked.  The
     segment will not be unlocked until its lock count is decremented to
     zero.

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

 Examples

     .  This example allocates a segment with _xvalloc() and locks it
        with _xvlock().  After a string is copied into the locked segment,
        the segment is unlocked and freed (with _xvunlock() and _xvfree()):

        // CA-Clipper include files
        #include "extend.api"
        #include "vm.api"

        // Microsoft C include files
        #include "string.h"

        // Prototype
        Boolean VMExample(char * spSrc);


        Boolean VMExample(char * spSrc)
        {
           HANDLE hSegment;
           char * spString;
           Boolean bResult = FALSE;

           if (hSegment = _xvalloc(strlen(spSrc) + 1, 0))
              {
              spString = _xvlock(hSegment);
              if (spString != NULL)
                 {
                 strcpy(spString, spSrc);

                 .
                 . <statements>
                 .

                 bResult = TRUE;

                 _xvunlock(hSegment);
                 }
              _xvfree(hSegment);
              }

           return (bResult);
        }

 Files  Library is CLIPPER.LIB, header file is Vm.api.