[<<Previous Entry] [^^Up^^] [Next Entry>>] [Menu] [About The Guide]
 _xvalloc()
 Allocate a VM segment
------------------------------------------------------------------------------
 C Prototype

     #include "vm.api"
     HANDLE _xvalloc(
                      USHORT uiSize,
                      USHORT uiFlags
                    )

 Arguments

     uiSize is the size of the segment to allocate in bytes.

     uiFlags is currently unused and must be set to zero.

 Returns

     If successful, _xvalloc() returns a 16-bit segment handle; otherwise, it
     returns zero.

 Description

     _xvalloc() allocates a VM segment, returning a handle that you can use
     in all subsequent VM operations involving that segment.

     Note:  To use the memory contained in the segment, your function
     must obtain a far pointer to physical memory by locking the segment with
     _xvlock() or _xvwire().

     Warning!  You must eventually use _xvfree() to free VM segments
     allocated by _xvalloc().

 Notes

     .  Maximum size:  The maximum number of bytes that can be allocated
        in a VM segment is 65,520, enough to hold the largest CA-Clipper
        string and a null terminator.

 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.


See Also: _xvheapnew() _xvfree() _xvlock() _xvrealloc()
This page created by ng2html v1.05, the Norton guide to HTML conversion utility. Written by Dave Pearson